webmcp-nexus-core 0.1.9

package/dist/index.js

@@ -0,0 +1,568 @@
+// src/ts-extractor.ts
+import nodePath from "path";
+import {
+  Project,
+  SyntaxKind
+} from "ts-morph";
+var REGISTRATION_FUNCTIONS = ["registerGlobalTools", "useWebMcpTools"];
+var isDebug = () => (process.env.DEBUG ?? "").toLowerCase().includes("webmcp");
+function resolveWithAlias(spec, alias) {
+  if (!alias) return null;
+  const keys = Object.keys(alias).sort((a, b) => b.length - a.length);
+  for (const key of keys) {
+    const target = alias[key];
+    if (typeof target !== "string") continue;
+    if (key.endsWith("$")) {
+      if (spec === key.slice(0, -1)) return target;
+      continue;
+    }
+    if (spec === key) return target;
+    if (spec.startsWith(key + "/")) {
+      return nodePath.join(target, spec.slice(key.length + 1));
+    }
+  }
+  return null;
+}
+function mapType(type) {
+  if (type.isString() || type.isStringLiteral()) return "string";
+  if (type.isNumber() || type.isNumberLiteral()) return "number";
+  if (type.isBoolean() || type.isBooleanLiteral()) return "boolean";
+  if (type.isArray()) return "array";
+  if (type.isUnion()) {
+    const filtered = type.getUnionTypes().filter((t) => !t.isUndefined() && !t.isNull());
+    if (filtered.length === 0) return "string";
+    if (filtered.length === 1) return mapType(filtered[0]);
+    if (filtered.every((t) => t.isStringLiteral())) return "string";
+    if (filtered.every((t) => t.isNumberLiteral())) return "number";
+    if (filtered.every((t) => t.isBooleanLiteral())) return "boolean";
+    return "string";
+  }
+  if (type.isObject() && !type.isArray()) return "object";
+  if (type.isNull() || type.isUndefined()) return "string";
+  if (type.isAny() || type.isUnknown()) return "string";
+  return "string";
+}
+function getArrayItemType(type) {
+  if (!type.isArray()) return void 0;
+  const typeArgs = type.getTypeArguments();
+  if (typeArgs.length > 0) {
+    return mapType(typeArgs[0]);
+  }
+  return "string";
+}
+function extractEnumValues(type) {
+  if (!type.isUnion()) return void 0;
+  const unionTypes = type.getUnionTypes().filter((t) => !t.isUndefined() && !t.isNull());
+  if (unionTypes.length === 0) return void 0;
+  if (unionTypes.every((t) => t.isStringLiteral())) {
+    return unionTypes.map((t) => t.getLiteralValue());
+  }
+  return void 0;
+}
+function getPropertyDescription(symbol) {
+  const declarations = symbol.getDeclarations();
+  for (const decl of declarations) {
+    const jsDocs = decl.getJsDocs?.();
+    if (jsDocs && jsDocs.length > 0) {
+      const comment = jsDocs[0].getDescription?.();
+      if (comment) return comment.trim();
+    }
+    const fullText = decl.getFullText();
+    const match = fullText.match(/\/\*\*\s*(.*?)\s*\*\//s);
+    if (match) {
+      const raw = match[1].split("\n").map((line) => line.replace(/^\s*\*\s?/, "").trim()).filter(Boolean).join(" ");
+      if (raw) return raw;
+    }
+  }
+  return void 0;
+}
+function extractProperties(type, depth = 0) {
+  const properties = [];
+  for (const prop of type.getProperties()) {
+    const propType = prop.getValueDeclaration() ? prop.getTypeAtLocation(prop.getValueDeclaration()) : prop.getDeclaredType();
+    const isOptional = prop.isOptional();
+    const enumValues = extractEnumValues(propType);
+    const mappedType = mapType(propType);
+    let nestedProperties;
+    if (mappedType === "object" && depth < 3) {
+      nestedProperties = extractProperties(propType, depth + 1);
+    }
+    properties.push({
+      name: prop.getName(),
+      type: mappedType,
+      description: getPropertyDescription(prop),
+      required: !isOptional,
+      enumValues,
+      itemType: getArrayItemType(propType),
+      properties: nestedProperties
+    });
+  }
+  return properties;
+}
+function extractFunctionMetadata(node, _sourceFile) {
+  let description = "";
+  let readOnly = false;
+  let properties = [];
+  if (node.getKind() === SyntaxKind.FunctionDeclaration) {
+    const funcDecl = node;
+    const jsDocs = funcDecl.getJsDocs();
+    if (jsDocs.length > 0) {
+      description = jsDocs[0].getDescription()?.trim() ?? "";
+      const tags = jsDocs[0].getTags();
+      readOnly = tags.some((tag) => tag.getTagName() === "readonly");
+    }
+    const params = funcDecl.getParameters();
+    if (params.length > 0) {
+      const paramType = params[0].getType();
+      properties = extractProperties(paramType);
+    }
+    return { description, readOnly, properties };
+  }
+  if (node.getKind() === SyntaxKind.ArrowFunction || node.getKind() === SyntaxKind.FunctionExpression) {
+    const funcNode = node;
+    const parent = funcNode.getParent();
+    if (parent) {
+      let varStatement;
+      if (parent.getKind() === SyntaxKind.VariableDeclaration) {
+        varStatement = parent.getParent()?.getParent();
+      } else if (parent.getKind() === SyntaxKind.CallExpression) {
+        const callParent = parent.getParent();
+        if (callParent?.getKind() === SyntaxKind.VariableDeclaration) {
+          varStatement = callParent.getParent()?.getParent();
+        }
+      }
+      if (varStatement) {
+        const jsDocs = varStatement.getJsDocs?.();
+        if (jsDocs && jsDocs.length > 0) {
+          description = jsDocs[0].getDescription?.()?.trim() ?? "";
+          const tags = jsDocs[0].getTags?.() ?? [];
+          readOnly = tags.some((tag) => tag.getTagName() === "readonly");
+        }
+      }
+    }
+    const params = funcNode.getParameters();
+    if (params.length > 0) {
+      const paramType = params[0].getType();
+      properties = extractProperties(paramType);
+    }
+    return { description, readOnly, properties };
+  }
+  return { description, readOnly, properties };
+}
+function extractToolFromBindingElement(bindingElement, toolName, relPath) {
+  const be = bindingElement;
+  const nameNode = be.getNameNode?.();
+  if (!nameNode) return null;
+  const bindingType = nameNode.getType();
+  const callSignatures = bindingType.getCallSignatures();
+  if (callSignatures.length === 0) return null;
+  let properties = [];
+  const sig = callSignatures[0];
+  const sigParams = sig.getParameters();
+  if (sigParams.length > 0) {
+    const paramSym = sigParams[0];
+    const paramDecls = paramSym.getDeclarations();
+    if (paramDecls.length > 0) {
+      const paramType = paramSym.getTypeAtLocation(paramDecls[0]);
+      properties = extractProperties(paramType);
+    }
+  }
+  const propertyNameNode = be.getPropertyNameNode?.();
+  const propertyName = propertyNameNode ? propertyNameNode.getText() : toolName;
+  let description = "";
+  let readOnly = false;
+  const objectBindingPattern = bindingElement.getParent();
+  const variableDecl = objectBindingPattern?.getParent();
+  if (variableDecl && variableDecl.getKind() === SyntaxKind.VariableDeclaration) {
+    const initializer = variableDecl.getInitializer?.();
+    if (initializer) {
+      const initType = initializer.getType();
+      let propSym = initType.getProperty(propertyName);
+      if (!propSym && initType.isUnion?.()) {
+        for (const t of initType.getUnionTypes()) {
+          if (t.isNull?.() || t.isUndefined?.()) continue;
+          propSym = t.getProperty(propertyName);
+          if (propSym) break;
+        }
+      }
+      if (propSym) {
+        const propDecls = propSym.getDeclarations();
+        for (const pdecl of propDecls) {
+          const jsDocs = pdecl.getJsDocs?.();
+          if (jsDocs && jsDocs.length > 0) {
+            description = jsDocs[0].getDescription?.()?.trim() ?? "";
+            const tags = jsDocs[0].getTags?.() ?? [];
+            readOnly = tags.some((t) => t.getTagName() === "readonly");
+            break;
+          }
+          const fullText = pdecl.getFullText();
+          const m = fullText.match(/\/\*\*\s*([\s\S]*?)\s*\*\//);
+          if (m) {
+            const raw = m[1].split("\n").map((line) => line.replace(/^\s*\*\s?/, "").trim()).filter(Boolean).join(" ");
+            if (raw) {
+              description = raw;
+              if (/@readonly\b/.test(m[1])) readOnly = true;
+              break;
+            }
+          }
+        }
+      }
+    }
+  }
+  return {
+    name: toolName,
+    description,
+    properties,
+    readOnly,
+    sourceFile: relPath,
+    injectionTarget: toolName
+  };
+}
+function resolveObjectLiteralArg(arg, sourceFile, project, projectRoot) {
+  const tools = [];
+  if (arg.getKind() !== SyntaxKind.ObjectLiteralExpression) return tools;
+  const objLiteral = arg;
+  const filePath = sourceFile.getFilePath();
+  const baseDir = projectRoot ?? process.cwd();
+  const relPath = "./" + nodePath.relative(baseDir, filePath).replace(/\.tsx?$/, "");
+  for (const prop of objLiteral.getProperties()) {
+    let toolName;
+    let valueNode;
+    if (prop.getKind() === SyntaxKind.ShorthandPropertyAssignment) {
+      toolName = prop.getName();
+      const tc = project.getTypeChecker().compilerObject;
+      const valueSym = tc.getShorthandAssignmentValueSymbol(prop.compilerNode);
+      if (!valueSym || !valueSym.declarations || valueSym.declarations.length === 0) continue;
+      const decl = sourceFile._getNodeFromCompilerNode(valueSym.declarations[0]);
+      if (decl.getKind() === SyntaxKind.VariableDeclaration) {
+        valueNode = decl.getInitializer?.();
+      } else if (decl.getKind() === SyntaxKind.FunctionDeclaration) {
+        valueNode = decl;
+      } else if (decl.getKind() === SyntaxKind.Parameter) {
+        continue;
+      } else if (decl.getKind() === SyntaxKind.BindingElement) {
+        const tool = extractToolFromBindingElement(decl, toolName, relPath);
+        if (tool) tools.push(tool);
+        continue;
+      }
+    } else if (prop.getKind() === SyntaxKind.PropertyAssignment) {
+      toolName = prop.getName();
+      valueNode = prop.getInitializer?.();
+    } else {
+      continue;
+    }
+    if (!valueNode) continue;
+    let funcNode = valueNode;
+    if (valueNode.getKind() === SyntaxKind.CallExpression) {
+      const callExpr = valueNode;
+      const callName = callExpr.getExpression().getText();
+      if (callName === "useCallback") {
+        const args = callExpr.getArguments();
+        if (args.length > 0) {
+          funcNode = args[0];
+        }
+      }
+    }
+    if (funcNode.getKind() === SyntaxKind.Identifier) {
+      const symbol = funcNode.getSymbol();
+      if (symbol) {
+        const declarations = symbol.getDeclarations();
+        if (declarations.length > 0) {
+          const decl = declarations[0];
+          if (decl.getKind() === SyntaxKind.FunctionDeclaration) {
+            funcNode = decl;
+          } else if (decl.getKind() === SyntaxKind.VariableDeclaration) {
+            const init = decl.getInitializer?.();
+            if (init) funcNode = init;
+          }
+        }
+      }
+    }
+    const metadata = extractFunctionMetadata(funcNode, sourceFile);
+    tools.push({
+      name: toolName,
+      description: metadata.description,
+      properties: metadata.properties,
+      readOnly: metadata.readOnly,
+      sourceFile: relPath,
+      injectionTarget: toolName
+    });
+  }
+  return tools;
+}
+function resolveNamespaceImportArg(arg, sourceFile, project, projectRoot, alias) {
+  const tools = [];
+  if (arg.getKind() !== SyntaxKind.Identifier) return tools;
+  const identifier = arg;
+  const symbol = identifier.getSymbol();
+  if (!symbol) return tools;
+  const declarations = symbol.getDeclarations();
+  if (declarations.length === 0) return tools;
+  const decl = declarations[0];
+  if (decl.getKind() !== SyntaxKind.NamespaceImport) return tools;
+  const importDecl = decl.getParent()?.getParent();
+  if (!importDecl) return tools;
+  const moduleSpecifier = importDecl.getModuleSpecifierValue?.();
+  if (!moduleSpecifier) return tools;
+  const currentDir = nodePath.dirname(sourceFile.getFilePath());
+  const aliasResolved = resolveWithAlias(moduleSpecifier, alias);
+  let resolvedPath = null;
+  if (aliasResolved) {
+    resolvedPath = nodePath.isAbsolute(aliasResolved) ? aliasResolved : nodePath.resolve(projectRoot ?? currentDir, aliasResolved);
+  } else if (moduleSpecifier.startsWith(".") || nodePath.isAbsolute(moduleSpecifier)) {
+    resolvedPath = nodePath.resolve(currentDir, moduleSpecifier);
+  }
+  if (!resolvedPath) {
+    if (isDebug()) {
+      console.warn(
+        `[webmcp] skip bare module specifier "${moduleSpecifier}" in ${sourceFile.getFilePath()} (no alias match)`
+      );
+    }
+    return tools;
+  }
+  const possibleExtensions = [".ts", ".tsx", "/index.ts", "/index.tsx"];
+  let targetFile;
+  for (const ext of possibleExtensions) {
+    const tryPath = resolvedPath + ext;
+    targetFile = project.getSourceFile(tryPath);
+    if (targetFile) break;
+  }
+  if (!targetFile) {
+    for (const ext of possibleExtensions) {
+      const tryPath = resolvedPath + ext;
+      try {
+        targetFile = project.addSourceFileAtPath(tryPath);
+        if (targetFile) break;
+      } catch (err) {
+        if (isDebug()) {
+          console.warn(`[webmcp] failed to add source file: ${tryPath}`, err);
+        }
+      }
+    }
+  }
+  if (!targetFile) {
+    console.warn(
+      `[webmcp] cannot resolve module "${moduleSpecifier}" from ${sourceFile.getFilePath()}. Tried extensions: ${possibleExtensions.join(", ")}. Resolved base: ${resolvedPath}`
+    );
+    return tools;
+  }
+  const namespaceName = identifier.getText();
+  const baseDir = projectRoot ?? process.cwd();
+  const relPath = "./" + nodePath.relative(baseDir, targetFile.getFilePath()).replace(/\.tsx?$/, "");
+  for (const exportedDecl of targetFile.getExportedDeclarations()) {
+    const [exportName, declarations2] = exportedDecl;
+    if (declarations2.length === 0) continue;
+    const exportNode = declarations2[0];
+    let funcNode;
+    if (exportNode.getKind() === SyntaxKind.FunctionDeclaration) {
+      funcNode = exportNode;
+    } else if (exportNode.getKind() === SyntaxKind.VariableDeclaration) {
+      const init = exportNode.getInitializer?.();
+      if (init && (init.getKind() === SyntaxKind.ArrowFunction || init.getKind() === SyntaxKind.FunctionExpression)) {
+        funcNode = init;
+      }
+    }
+    if (!funcNode) continue;
+    const metadata = extractFunctionMetadata(funcNode, targetFile);
+    tools.push({
+      name: exportName,
+      description: metadata.description,
+      properties: metadata.properties,
+      readOnly: metadata.readOnly,
+      sourceFile: relPath,
+      injectionTarget: `${namespaceName}.${exportName}`
+    });
+  }
+  return tools;
+}
+function extractToolsFromFile(fileContent, filePath, projectRoot, alias) {
+  const hasRegistration = REGISTRATION_FUNCTIONS.some((fn) => fileContent.includes(fn));
+  if (!hasRegistration) return null;
+  if (isDebug()) {
+    console.log(
+      `[webmcp] extractToolsFromFile: ${filePath}, projectRoot=${projectRoot ?? "(none)"}`
+    );
+  }
+  try {
+    const project = new Project({
+      compilerOptions: {
+        strict: true,
+        target: 99,
+        // ESNext
+        module: 99,
+        // ESNext
+        jsx: 4,
+        // ReactJSX
+        moduleResolution: 100,
+        // Bundler
+        esModuleInterop: true,
+        ...projectRoot ? { rootDir: projectRoot, baseUrl: projectRoot } : {}
+      },
+      skipAddingFilesFromTsConfig: true,
+      useInMemoryFileSystem: false
+    });
+    const sourceFile = project.createSourceFile(filePath, fileContent, {
+      overwrite: true
+    });
+    const result = {
+      tools: [],
+      registrationCalls: []
+    };
+    sourceFile.forEachDescendant((node) => {
+      if (node.getKind() !== SyntaxKind.CallExpression) return;
+      const callExpr = node;
+      const exprText = callExpr.getExpression().getText();
+      if (!REGISTRATION_FUNCTIONS.includes(exprText)) return;
+      result.registrationCalls.push({
+        type: exprText,
+        start: callExpr.getStart()
+      });
+      const args = callExpr.getArguments();
+      for (const arg of args) {
+        if (arg.getKind() === SyntaxKind.ObjectLiteralExpression) {
+          const tools = resolveObjectLiteralArg(arg, sourceFile, project, projectRoot);
+          result.tools.push(...tools);
+        } else if (arg.getKind() === SyntaxKind.Identifier) {
+          const tools = resolveNamespaceImportArg(arg, sourceFile, project, projectRoot, alias);
+          result.tools.push(...tools);
+        }
+      }
+    });
+    if (result.tools.length === 0) {
+      if (isDebug()) {
+        console.warn(`[webmcp] no tools extracted from ${filePath}`);
+      }
+      return null;
+    }
+    return result;
+  } catch (err) {
+    console.warn(
+      `[webmcp] extractToolsFromFile failed for ${filePath}:`,
+      err instanceof Error ? err.message : err
+    );
+    if (isDebug()) {
+      console.warn(`[webmcp] full error:`, err);
+    }
+    return null;
+  }
+}
+
+// src/schema-generator.ts
+function generateSchema(properties, description) {
+  const schema = {
+    type: "object",
+    properties: {},
+    required: []
+  };
+  if (description) {
+    schema.description = description;
+  }
+  for (const prop of properties) {
+    const propSchema = mapTypeToSchema(prop);
+    schema.properties[prop.name] = propSchema;
+    if (prop.required) {
+      schema.required.push(prop.name);
+    }
+  }
+  if (schema.required.length === 0) {
+    delete schema.required;
+  }
+  return schema;
+}
+function generateSchemaInjectionCode(injectionTarget, description, properties, readOnly) {
+  const inputSchema = generateSchema(properties);
+  delete inputSchema.description;
+  const schemaObj = {
+    description,
+    inputSchema,
+    readOnly
+  };
+  return `${injectionTarget}.__webmcpSchema = ${JSON.stringify(schemaObj, null, 2)};`;
+}
+function mapTypeToSchema(prop) {
+  const schema = { type: "string" };
+  if (prop.description) {
+    schema.description = prop.description;
+  }
+  if (prop.enumValues && prop.enumValues.length > 0) {
+    schema.type = "string";
+    schema.enum = prop.enumValues;
+    return schema;
+  }
+  switch (prop.type) {
+    case "string":
+      schema.type = "string";
+      break;
+    case "number":
+      schema.type = "number";
+      break;
+    case "boolean":
+      schema.type = "boolean";
+      break;
+    case "array":
+      schema.type = "array";
+      if (prop.itemType) {
+        schema.items = { type: prop.itemType };
+      }
+      break;
+    case "object":
+      schema.type = "object";
+      if (prop.properties && prop.properties.length > 0) {
+        schema.properties = {};
+        const required = [];
+        for (const subProp of prop.properties) {
+          schema.properties[subProp.name] = mapTypeToSchema(subProp);
+          if (subProp.required) required.push(subProp.name);
+        }
+        if (required.length > 0) schema.required = required;
+      }
+      break;
+    default:
+      schema.type = "string";
+  }
+  return schema;
+}
+
+// src/transform.ts
+var isDebug2 = () => (process.env.DEBUG ?? "").toLowerCase().includes("webmcp");
+function transformCode(code, filePath, options = {}) {
+  if (!code.includes("registerGlobalTools") && !code.includes("useWebMcpTools")) {
+    return { code, transformed: false };
+  }
+  if (isDebug2()) {
+    console.log(
+      `[webmcp] transformCode: ${filePath}, projectRoot=${options.projectRoot ?? "(none)"}`
+    );
+  }
+  const result = extractToolsFromFile(code, filePath, options.projectRoot, options.alias);
+  if (!result || result.tools.length === 0) {
+    return { code, transformed: false };
+  }
+  const injections = [];
+  for (const tool of result.tools) {
+    const injectionCode = generateSchemaInjectionCode(
+      tool.injectionTarget,
+      tool.description,
+      tool.properties,
+      tool.readOnly
+    );
+    injections.push(injectionCode);
+  }
+  if (injections.length === 0) {
+    return { code, transformed: false };
+  }
+  const firstCall = result.registrationCalls.sort((a, b) => a.start - b.start)[0];
+  const injectionBlock = "\n// [webmcp-nexus-core] \u6784\u5EFA\u65F6\u6CE8\u5165\u7684 schema \u5143\u6570\u636E\n" + injections.join("\n") + "\n";
+  const newCode = code.slice(0, firstCall.start) + injectionBlock + code.slice(firstCall.start);
+  return { code: newCode, transformed: true };
+}
+export {
+  extractProperties,
+  extractToolsFromFile,
+  generateSchema,
+  generateSchemaInjectionCode,
+  mapType,
+  mapTypeToSchema,
+  resolveWithAlias,
+  transformCode
+};

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "webmcp-nexus-core",
+  "version": "0.1.9",
+  "description": "Core logic for WebMCP build plugins - TypeScript type extraction and JSON Schema generation",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "ts-morph": "^28.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.12.2",
+    "tsup": "^8.5.0",
+    "vitest": "^3.1.3"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}