webmcp-nexus-core 0.1.9

package/dist/index.d.cts

@@ -0,0 +1,129 @@
+import { Type } from 'ts-morph';
+
+/**
+ * 将 TypeScript 类型信息转换为 JSON Schema。
+ * 支持的映射规则见设计文档 3.2 节。
+ */
+interface JsonSchema {
+    type: string;
+    description?: string;
+    properties?: Record<string, JsonSchema>;
+    required?: string[];
+    items?: JsonSchema;
+    enum?: string[];
+}
+interface PropertyInfo {
+    name: string;
+    type: string;
+    description?: string;
+    required: boolean;
+    enumValues?: string[];
+    itemType?: string;
+    properties?: PropertyInfo[];
+}
+/**
+ * 从提取到的属性信息生成 JSON Schema
+ */
+declare function generateSchema(properties: PropertyInfo[], description?: string): JsonSchema;
+/**
+ * 生成 __webmcpSchema 属性注入代码。
+ *
+ * 输出形如：
+ * ```
+ * target.__webmcpSchema = { description: "...", inputSchema: {...}, readOnly: false };
+ * ```
+ *
+ * @param injectionTarget - 注入目标表达式（如 "searchInPanel" 或 "userApi.getUser"）
+ * @param description - 工具描述
+ * @param properties - 参数属性列表
+ * @param readOnly - 是否只读
+ * @returns 注入代码字符串
+ */
+declare function generateSchemaInjectionCode(injectionTarget: string, description: string, properties: PropertyInfo[], readOnly: boolean): string;
+declare function mapTypeToSchema(prop: PropertyInfo): JsonSchema;
+
+/**
+ * TypeScript 类型提取器（v2 — 逆向追踪机制）。
+ *
+ * 从 registerGlobalTools() / useWebMcpTools() 调用向上追踪到函数定义，
+ * 使用 ts-morph 解析参数类型 + JSDoc 注释，提取工具元数据。
+ *
+ * 支持两种参数形式：
+ * 1. 对象字面量：{ fn1, fn2 } → 从 key 追踪到函数定义
+ * 2. Namespace import：import * as api from './module' → 解析源模块所有导出函数
+ */
+
+/** 提取出的工具元数据 */
+interface ExtractedTool {
+    /** 工具名（对象 key 或导出函数名） */
+    name: string;
+    /** JSDoc 描述 */
+    description: string;
+    /** 参数属性列表 */
+    properties: PropertyInfo[];
+    /** 是否为只读工具（@readonly 标签） */
+    readOnly: boolean;
+    /** 来源文件路径（用于调试） */
+    sourceFile: string;
+    /**
+     * 注入目标表达式。
+     * 对于对象字面量参数中的本地变量：变量名，如 "searchInPanel"
+     * 对于 namespace import：namespace.exportName，如 "userApi.getUser"
+     */
+    injectionTarget: string;
+}
+/** 注册调用的提取结果 */
+interface ExtractionResult {
+    /** 提取到的工具列表 */
+    tools: ExtractedTool[];
+    /** 注册调用的位置信息（用于在调用前注入代码） */
+    registrationCalls: {
+        /** 调用类型 */
+        type: 'registerGlobalTools' | 'useWebMcpTools';
+        /** 调用在源码中的起始位置（字符偏移量） */
+        start: number;
+    }[];
+}
+/**
+ * 模块路径别名映射（兼容 webpack / vite 的 alias 配置）。
+ * key 为别名前缀（可用 `$` 后缀表示精确匹配），value 为目标绝对路径或相对 projectRoot 的路径。
+ */
+type AliasMap = Record<string, string>;
+/**
+ * 根据 alias 映射解析模块说明符。
+ * 支持 webpack 风格：
+ *   - 精确匹配：key 以 `$` 结尾（如 `xyz$`），仅在 spec 完全等于 `xyz` 时命中
+ *   - 前缀匹配：spec 等于 key 或以 `key + '/'` 开头
+ * 最长前缀优先。命中时返回替换后的路径，未命中返回 null。
+ */
+declare function resolveWithAlias(spec: string, alias?: AliasMap): string | null;
+/**
+ * 将 ts-morph Type 映射为简化的类型字符串（JSON Schema type）
+ */
+declare function mapType(type: Type): string;
+/** 从一个 Type 提取所有属性信息 */
+declare function extractProperties(type: Type, depth?: number): PropertyInfo[];
+/**
+ * 从源文件中提取所有 registerGlobalTools / useWebMcpTools 调用引用的工具
+ *
+ * @param fileContent - 源文件内容
+ * @param filePath - 源文件绝对路径
+ * @returns 提取结果，包含工具列表和注册调用位置信息
+ */
+declare function extractToolsFromFile(fileContent: string, filePath: string, projectRoot?: string, alias?: AliasMap): ExtractionResult | null;
+
+interface TransformOptions {
+    projectRoot?: string;
+    /**
+     * 构建工具的模块路径 alias 映射（已归一化为 prefix → 目标路径）。
+     * 用于解析 `import * as api from '@alias/xxx'` 类形式的模块说明符。
+     */
+    alias?: AliasMap;
+}
+interface TransformResult {
+    code: string;
+    transformed: boolean;
+}
+declare function transformCode(code: string, filePath: string, options?: TransformOptions): TransformResult;
+
+export { type AliasMap, type ExtractedTool, type ExtractionResult, type JsonSchema, type PropertyInfo, type TransformOptions, type TransformResult, extractProperties, extractToolsFromFile, generateSchema, generateSchemaInjectionCode, mapType, mapTypeToSchema, resolveWithAlias, transformCode };

package/dist/index.d.ts

@@ -0,0 +1,129 @@
+import { Type } from 'ts-morph';
+
+/**
+ * 将 TypeScript 类型信息转换为 JSON Schema。
+ * 支持的映射规则见设计文档 3.2 节。
+ */
+interface JsonSchema {
+    type: string;
+    description?: string;
+    properties?: Record<string, JsonSchema>;
+    required?: string[];
+    items?: JsonSchema;
+    enum?: string[];
+}
+interface PropertyInfo {
+    name: string;
+    type: string;
+    description?: string;
+    required: boolean;
+    enumValues?: string[];
+    itemType?: string;
+    properties?: PropertyInfo[];
+}
+/**
+ * 从提取到的属性信息生成 JSON Schema
+ */
+declare function generateSchema(properties: PropertyInfo[], description?: string): JsonSchema;
+/**
+ * 生成 __webmcpSchema 属性注入代码。
+ *
+ * 输出形如：
+ * ```
+ * target.__webmcpSchema = { description: "...", inputSchema: {...}, readOnly: false };
+ * ```
+ *
+ * @param injectionTarget - 注入目标表达式（如 "searchInPanel" 或 "userApi.getUser"）
+ * @param description - 工具描述
+ * @param properties - 参数属性列表
+ * @param readOnly - 是否只读
+ * @returns 注入代码字符串
+ */
+declare function generateSchemaInjectionCode(injectionTarget: string, description: string, properties: PropertyInfo[], readOnly: boolean): string;
+declare function mapTypeToSchema(prop: PropertyInfo): JsonSchema;
+
+/**
+ * TypeScript 类型提取器（v2 — 逆向追踪机制）。
+ *
+ * 从 registerGlobalTools() / useWebMcpTools() 调用向上追踪到函数定义，
+ * 使用 ts-morph 解析参数类型 + JSDoc 注释，提取工具元数据。
+ *
+ * 支持两种参数形式：
+ * 1. 对象字面量：{ fn1, fn2 } → 从 key 追踪到函数定义
+ * 2. Namespace import：import * as api from './module' → 解析源模块所有导出函数
+ */
+
+/** 提取出的工具元数据 */
+interface ExtractedTool {
+    /** 工具名（对象 key 或导出函数名） */
+    name: string;
+    /** JSDoc 描述 */
+    description: string;
+    /** 参数属性列表 */
+    properties: PropertyInfo[];
+    /** 是否为只读工具（@readonly 标签） */
+    readOnly: boolean;
+    /** 来源文件路径（用于调试） */
+    sourceFile: string;
+    /**
+     * 注入目标表达式。
+     * 对于对象字面量参数中的本地变量：变量名，如 "searchInPanel"
+     * 对于 namespace import：namespace.exportName，如 "userApi.getUser"
+     */
+    injectionTarget: string;
+}
+/** 注册调用的提取结果 */
+interface ExtractionResult {
+    /** 提取到的工具列表 */
+    tools: ExtractedTool[];
+    /** 注册调用的位置信息（用于在调用前注入代码） */
+    registrationCalls: {
+        /** 调用类型 */
+        type: 'registerGlobalTools' | 'useWebMcpTools';
+        /** 调用在源码中的起始位置（字符偏移量） */
+        start: number;
+    }[];
+}
+/**
+ * 模块路径别名映射（兼容 webpack / vite 的 alias 配置）。
+ * key 为别名前缀（可用 `$` 后缀表示精确匹配），value 为目标绝对路径或相对 projectRoot 的路径。
+ */
+type AliasMap = Record<string, string>;
+/**
+ * 根据 alias 映射解析模块说明符。
+ * 支持 webpack 风格：
+ *   - 精确匹配：key 以 `$` 结尾（如 `xyz$`），仅在 spec 完全等于 `xyz` 时命中
+ *   - 前缀匹配：spec 等于 key 或以 `key + '/'` 开头
+ * 最长前缀优先。命中时返回替换后的路径，未命中返回 null。
+ */
+declare function resolveWithAlias(spec: string, alias?: AliasMap): string | null;
+/**
+ * 将 ts-morph Type 映射为简化的类型字符串（JSON Schema type）
+ */
+declare function mapType(type: Type): string;
+/** 从一个 Type 提取所有属性信息 */
+declare function extractProperties(type: Type, depth?: number): PropertyInfo[];
+/**
+ * 从源文件中提取所有 registerGlobalTools / useWebMcpTools 调用引用的工具
+ *
+ * @param fileContent - 源文件内容
+ * @param filePath - 源文件绝对路径
+ * @returns 提取结果，包含工具列表和注册调用位置信息
+ */
+declare function extractToolsFromFile(fileContent: string, filePath: string, projectRoot?: string, alias?: AliasMap): ExtractionResult | null;
+
+interface TransformOptions {
+    projectRoot?: string;
+    /**
+     * 构建工具的模块路径 alias 映射（已归一化为 prefix → 目标路径）。
+     * 用于解析 `import * as api from '@alias/xxx'` 类形式的模块说明符。
+     */
+    alias?: AliasMap;
+}
+interface TransformResult {
+    code: string;
+    transformed: boolean;
+}
+declare function transformCode(code: string, filePath: string, options?: TransformOptions): TransformResult;
+
+export { type AliasMap, type ExtractedTool, type ExtractionResult, type JsonSchema, type PropertyInfo, type TransformOptions, type TransformResult, extractProperties, extractToolsFromFile, generateSchema, generateSchemaInjectionCode, mapType, mapTypeToSchema, resolveWithAlias, transformCode };