@pubinfo/devtools 2.0.15 → 2.1.1

package/dist/index.js

@@ -1,40 +1,592 @@
-import { addCustomTab } from "@vue/devtools-api";
+import { t as DIR_CLIENT } from "./dirs-BjObhKjC.js";
+import { basename, dirname, extname, join, relative } from "node:path";
+import { pathToFileURL } from "node:url";
+import sirv from "sirv";
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { readdir } from "node:fs/promises";
 
-//#region src/chrome.ts
-function setupChromeDevtoolsPanel() {
-	addCustomTab({
-		name: "chrome-devtools",
-		title: "Chrome Devtools",
-		icon: "https://icones.elonehoo.cn/logos-chrome.svg",
-		view: {
-			type: "iframe",
-			src: "/__chrome_devtools/"
-		},
-		category: "app"
+//#region src/server/controller/api.ts
+const REQUEST_MODULE_EXTENSIONS = [
+	".ts",
+	".mts",
+	".cts",
+	".tsx",
+	".js",
+	".mjs",
+	".cjs",
+	".jsx"
+];
+function escapeRegExp(value) {
+	return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function normalizePath(filePath) {
+	return filePath.replace(/\\/g, "/");
+}
+/**
+* 构造别名解析器集合。
+*
+* 支持以下映射：
+* - '@/x'、'~/x' → <root>/src/x
+* - tsconfig.json 中 compilerOptions.paths 定义的别名（含 * 通配符）
+*
+* 实现采用正则表驱动：传入 specifier 后逐条匹配并映射为绝对路径字符串。
+*/
+function createAliasResolver(root) {
+	const entries = [{
+		match: /^@\/(.+)$/,
+		map: (match) => join(root, "src", match[1])
+	}, {
+		match: /^~\/(.+)$/,
+		map: (match) => join(root, "src", match[1])
+	}];
+	const tsconfigCandidates = [join(root, "tsconfig.json"), join(root, "tsconfig.app.json")];
+	for (const configPath of tsconfigCandidates) {
+		if (!existsSync(configPath)) continue;
+		try {
+			const compilerOptions = JSON.parse(readFileSync(configPath, "utf-8"))?.compilerOptions ?? {};
+			const baseUrl = compilerOptions.baseUrl ? join(root, compilerOptions.baseUrl) : root;
+			const paths = compilerOptions.paths;
+			if (!paths || typeof paths !== "object") continue;
+			for (const [key, values] of Object.entries(paths)) {
+				const targets = Array.isArray(values) ? values : [values];
+				const hasWildcard = key.includes("*");
+				const pattern = /* @__PURE__ */ new RegExp(`^${escapeRegExp(key).replace(/\\\*/g, "(.+)")}$`);
+				targets.forEach((targetPath) => {
+					if (typeof targetPath !== "string") return;
+					const normalizedTarget = targetPath.replace(/\\/g, "/");
+					entries.push({
+						match: pattern,
+						map: (match) => {
+							if (hasWildcard) {
+								const wildcard = match[1] ?? "";
+								return join(baseUrl, normalizedTarget.replace(/\*/g, wildcard));
+							}
+							return join(baseUrl, normalizedTarget);
+						}
+					});
+				});
+			}
+		} catch {}
+	}
+	return entries;
+}
+/**
+* 在若干后缀（ts/tsx/js/...）与 index 文件中尝试解析具体文件。
+*
+* - candidate 可能未带扩展名，函数会尝试附加扩展与目录下 index.xxx。
+* - 仅返回存在且确认为文件的路径；失败返回 undefined。
+*/
+function resolveWithExtensions(candidate) {
+	const candidates = [candidate];
+	if (!/\.[^/\\]+$/.test(candidate)) REQUEST_MODULE_EXTENSIONS.forEach((ext) => {
+		candidates.push(`${candidate}${ext}`);
+		candidates.push(join(candidate, `index${ext}`));
 	});
+	for (const file of candidates) if (existsSync(file)) try {
+		if (statSync(file).isFile()) return file;
+	} catch {}
+}
+/**
+* 依据导入路径与导入者位置，解析出相对于项目根目录的模块文件路径。
+*
+* 支持：
+* - 相对路径（./x、../x）
+* - 绝对路径（/x → <root>/x）
+* - 别名（来自 createAliasResolver 的 entries）
+* - 退化支持 '@/x' 或 '~/x' 当 paths 未配置但文件位于 <root>/src 下
+*/
+function resolveRequestModulePath(specifier, importerPath, root, aliasEntries) {
+	const importerDir = dirname(importerPath);
+	let absoluteCandidate;
+	if (specifier.startsWith(".")) absoluteCandidate = join(importerDir, specifier);
+	else if (specifier.startsWith("/")) absoluteCandidate = join(root, specifier.replace(/^\//, ""));
+	else for (const entry of aliasEntries) {
+		const match = entry.match.exec(specifier);
+		if (match) {
+			absoluteCandidate = entry.map(match);
+			break;
+		}
+	}
+	if (!absoluteCandidate && (specifier.startsWith("@/") || specifier.startsWith("~/"))) {
+		const markerIndex = normalizePath(importerPath).lastIndexOf("/src/");
+		if (markerIndex !== -1) absoluteCandidate = join(importerPath.slice(0, markerIndex), "src", specifier.slice(2));
+	}
+	if (!absoluteCandidate) return;
+	const resolved = resolveWithExtensions(absoluteCandidate);
+	if (!resolved) return;
+	return normalizePath(relative(root, resolved));
+}
+/**
+* 查找项目根目录的 OpenAPI 配置文件。
+*
+* 约定优于配置：默认仅查找根目录下的 `openapi.config.ts`。
+* 如需扩展为支持更多命名/位置，可在此集中改造，避免影响调用方。
+*
+* @param root 项目根目录的绝对路径（即 Vite server.config.root）
+* @returns 如果存在则返回绝对路径，否则返回 null
+*/
+async function findOpenapiConfig(root) {
+	const configPath = join(root, "openapi.config.ts");
+	if (existsSync(configPath)) return configPath;
+	return null;
+}
+/**
+* 动态加载 OpenAPI 配置文件。
+*
+* 之所以使用动态 import 而非 require：
+* - 支持 ESM 项目
+* - 避免被打包时静态分析（保持运行时可替换）
+*
+* 注意：此函数在 devtools 插件的 Vite 环境中执行，允许使用 file:// URL。
+*
+* @param configPath 配置文件的绝对路径
+* @returns 解析后的配置对象（优先使用 module.default），失败时返回 null
+*/
+async function loadOpenapiConfig(configPath) {
+	try {
+		const fileUrl = pathToFileURL(configPath).href;
+		const extension = extname(configPath);
+		if (extension === ".ts" || extension === ".mts" || extension === ".cts") {
+			const { loadConfig } = await import("unconfig");
+			const result = await loadConfig({
+				cwd: dirname(configPath),
+				sources: [{
+					files: basename(configPath, extension),
+					extensions: [extension.slice(1)]
+				}],
+				merge: false
+			});
+			if (typeof result?.config === "undefined") return null;
+			return await Promise.resolve(result.config);
+		} else {
+			const module = await import(fileUrl);
+			return module.default || module;
+		}
+	} catch (error) {
+		console.error(`加载配置文件失败: ${error}`);
+		return null;
+	}
+}
+/**
+* 从 TypeScript 源文件内容中提取导出的 API 函数的元信息。
+*
+* 约定：
+* - 仅识别 `export function foo(...)` 的导出形式；若有 `const foo = () => {}` 请改为函数导出或扩展正则。
+* - 通过 JSDoc 约定读取三类元数据：
+*   - @description 文本说明
+*   - @url 接口路径（例如 /user/list）
+*   - @method 请求方法（GET/POST/...）
+* - 通过参数签名解析类型信息：
+*   - params: API.Xxx → 视为 query
+*   - body: API.Xxx → 视为 body
+*   - 泛型参数中的 `R = API.Xxx` → 视为返回类型
+*
+* 限制与注意：
+* - 该实现基于正则进行快速解析，无法覆盖所有 TS 语法边界；遇到复杂写法可改为 AST（ts-morph / @typescript-eslint/typescript-estree）。
+* - 若同一文件存在多种导出形式，请保持上述约定以获得稳定结果。
+*
+* @param content 源文件文本
+* @param filePath 相对于项目根目录的文件相对路径（用于展示）
+* @param requestClient 若源码中以 `import { foo as request }` 形式命名的请求实例名，用于偏好匹配应用端实例
+* @returns 解析得到的 API 函数列表
+*/
+function extractApiFunctions(content, filePath, requestClient, requestModulePath, requestModuleResolvedPath) {
+	const functions = [];
+	const functionRegex = /\/\*\*\s*\n([^*]*(?:\*(?!\/)[^*]*)*)\*\/\s*export\s+function\s+(\w+)[^(]*\(([^)]*)\)/g;
+	let match = functionRegex.exec(content);
+	while (match !== null) {
+		const [, jsdoc, functionName, params] = match;
+		const descMatch = /@description\s+(.+)/.exec(jsdoc);
+		const description = descMatch ? descMatch[1].trim() : void 0;
+		const urlMatch = /@url\s+(.+)/.exec(jsdoc);
+		const url = urlMatch ? urlMatch[1].trim() : "";
+		const methodMatch = /@method\s+(.+)/.exec(jsdoc);
+		const method = methodMatch ? methodMatch[1].trim() : "UNKNOWN";
+		let paramType;
+		let paramLocation;
+		const paramsMatch = /params:\s*(API\.\w+)/.exec(params);
+		const bodyMatch = /body:\s*(API\.\w+)/.exec(params);
+		if (paramsMatch) {
+			paramType = paramsMatch[1];
+			paramLocation = "query";
+		} else if (bodyMatch) {
+			paramType = bodyMatch[1];
+			paramLocation = "body";
+		}
+		let returnType;
+		const returnTypeMatch = /R\s*=\s*(API\.\w+)/.exec(params);
+		if (returnTypeMatch) returnType = returnTypeMatch[1];
+		functions.push({
+			name: functionName,
+			description,
+			url,
+			method,
+			file: filePath,
+			paramType,
+			paramLocation,
+			returnType,
+			requestClient,
+			requestModulePath,
+			requestModuleResolvedPath
+		});
+		match = functionRegex.exec(content);
+	}
+	return functions;
+}
+/**
+* 将 TypeScript 类型（字面量对象类型）解析为简化的 JSON Schema 片段。
+*
+* 目前仅对如下简单场景做支持：
+* - `type Xxx = { foo: string; bar?: number }`
+* - 行内 JSDoc `/** desc *\/` 写在属性前可作为 description。
+* - 属性类型仅做基础映射（string/number/boolean/Record/any/数组）
+*
+* 不支持/暂不支持：
+* - 嵌套类型、联合/交叉、索引类型、条件类型、接口继承等复杂语法。
+* - interface 的 body 解析（可按需扩展正则）。
+*
+* 若需要更完整能力，建议切换到 TS AST 或 json-schema-generator 工具链。
+*
+* @param content typings.d.ts 文件全文
+* @param typeName 形如 `API.UserQuery` 的带命名空间类型名
+* @returns 简化的 JSON Schema 对象；无法解析时返回 null
+*/
+function parseTypeToSchema(content, typeName) {
+	try {
+		const match = new RegExp(`type\\s+${typeName.split(".").pop()}\\s*=\\s*\\{([^}]*)\\}`, "s").exec(content);
+		if (!match) return null;
+		const typeBody = match[1];
+		const properties = {};
+		const required = [];
+		const lines = typeBody.split("\n");
+		for (const line of lines) {
+			const trimmed = line.trim();
+			if (!trimmed || trimmed.startsWith("//") || trimmed.startsWith("/*")) continue;
+			const propWithComment = /^\/\*\*\s*(.+?)\s*\*\/\s*(\w+)(\??):\s*(.+?);?$/.exec(trimmed);
+			const propWithoutComment = /^(\w+)(\??):\s*(.+?);?$/.exec(trimmed);
+			if (propWithComment) {
+				const [, description, propertyName, optional, propertyType] = propWithComment;
+				const isOptional = optional === "?";
+				const prop = { type: mapTsTypeToJsonType(propertyType) };
+				if (description) prop.description = description;
+				properties[propertyName] = prop;
+				if (!isOptional) required.push(propertyName);
+			} else if (propWithoutComment) {
+				const [, propertyName, optional, propertyType] = propWithoutComment;
+				const isOptional = optional === "?";
+				properties[propertyName] = { type: mapTsTypeToJsonType(propertyType) };
+				if (!isOptional) required.push(propertyName);
+			}
+		}
+		return {
+			type: "object",
+			properties,
+			required: required.length > 0 ? required : void 0
+		};
+	} catch (error) {
+		console.error(`解析类型 ${typeName} 失败:`, error);
+		return null;
+	}
+}
+/**
+* 将常见的 TypeScript 基础类型映射为 JSON Schema 的 `type`。
+*
+* @param tsType TypeScript 类型字面量（如 'string' | 'number[]' | 'Record<string, any>'）
+* @returns JSON Schema 的基础类型字符串
+*/
+function mapTsTypeToJsonType(tsType) {
+	const type = tsType.trim();
+	if (type === "string") return "string";
+	if (type === "number") return "number";
+	if (type === "boolean") return "boolean";
+	if (type === "any" || type.startsWith("Record<")) return "object";
+	if (type.endsWith("[]")) return "array";
+	return "string";
+}
+/**
+* 从 `typings.d.ts` 中提取类型清单（仅定位名称，不展开定义）。
+*
+* 约定：
+* - 在 `declare namespace Xxx { ... }` 范围内提取 `type` 与 `interface` 的标识符。
+* - 仅收集行首的声明行，记录其名称与文件路径，便于 UI 展示与 schema 进一步解析。
+*
+* @param content typings.d.ts 文件全文
+* @param filePath 相对项目根的文件路径
+* @returns 类型条目列表
+*/
+function extractTypes(content, filePath) {
+	const types = [];
+	const lines = content.split("\n");
+	let currentNamespace = "";
+	let inNamespace = false;
+	let braceCount = 0;
+	for (const line of lines) {
+		const namespaceMatch = /declare\s+namespace\s+(\w+)/.exec(line);
+		if (namespaceMatch) {
+			currentNamespace = namespaceMatch[1];
+			inNamespace = true;
+			braceCount = 0;
+		}
+		if (inNamespace) {
+			braceCount += (line.match(/\{/g) || []).length;
+			braceCount -= (line.match(/\}/g) || []).length;
+			if (braceCount === 0 && line.includes("}")) inNamespace = false;
+		}
+		if (inNamespace && currentNamespace) {
+			const typeMatch = /^\s*(type|interface)\s+(\w+)/.exec(line);
+			if (typeMatch) {
+				const typeName = typeMatch[2];
+				types.push({
+					name: `${currentNamespace}.${typeName}`,
+					file: filePath,
+					content: line.trim()
+				});
+			}
+		}
+	}
+	return types;
+}
+/**
+* 递归扫描给定目录以收集 API 函数与类型定义。
+*
+* 扫描规则：
+* - 识别 `typings.d.ts` → 提取类型并尝试为同目录的 API 函数生成参数/返回 schema。
+* - 识别 `*.ts`（排除 index.ts）→ 通过 JSDoc 与参数签名提取 API 函数信息。
+* - 递归子目录以形成模块（module.path 为相对目录）。
+*
+* @param dir 要扫描的目录绝对路径（通常来自配置的 output）
+* @param root 项目根目录绝对路径，用于计算相对路径与分组
+* @returns 模块列表，每个模块包含 functions 与 types
+*/
+async function scanApiDirectory(dir, root, aliasEntries) {
+	const modules = [];
+	if (!existsSync(dir)) return modules;
+	const entries = await readdir(dir, { withFileTypes: true });
+	let typingsContent = null;
+	for (const entry of entries) if (entry.isFile() && entry.name === "typings.d.ts") {
+		typingsContent = readFileSync(join(dir, entry.name), "utf-8");
+		break;
+	}
+	for (const entry of entries) {
+		const fullPath = join(dir, entry.name);
+		if (entry.isDirectory()) {
+			const subModules = await scanApiDirectory(fullPath, root, aliasEntries);
+			modules.push(...subModules);
+		} else if (entry.isFile() && entry.name.endsWith(".ts")) {
+			const content = readFileSync(fullPath, "utf-8");
+			const relativePath = relative(root, fullPath);
+			const requestImportMatch = /import\s*\{\s*([\w$]+)\s+as\s+request\s*\}\s*from\s*['"]([^'"]+)['"]/.exec(content);
+			const requestClient = requestImportMatch ? requestImportMatch[1] : void 0;
+			const requestModulePath = requestImportMatch ? requestImportMatch[2] : void 0;
+			const requestModuleResolvedPath = requestModulePath ? resolveRequestModulePath(requestModulePath, fullPath, root, aliasEntries) : void 0;
+			if (entry.name === "typings.d.ts") {
+				const types = extractTypes(content, relativePath);
+				if (types.length > 0) {
+					const moduleDir = relative(root, dir);
+					let module = modules.find((m) => m.path === moduleDir);
+					if (!module) {
+						module = {
+							path: moduleDir,
+							functions: [],
+							types: []
+						};
+						modules.push(module);
+					}
+					module.types.push(...types);
+				}
+			} else if (entry.name !== "index.ts") {
+				const functions = extractApiFunctions(content, relativePath, requestClient, requestModulePath, requestModuleResolvedPath);
+				if (functions.length > 0) {
+					const moduleDir = relative(root, dir);
+					let module = modules.find((m) => m.path === moduleDir);
+					if (!module) {
+						module = {
+							path: moduleDir,
+							functions: [],
+							types: []
+						};
+						modules.push(module);
+					}
+					if (typingsContent) for (const func of functions) {
+						if (func.paramType) {
+							const schema = parseTypeToSchema(typingsContent, func.paramType);
+							if (schema) func.paramSchema = schema;
+						}
+						if (func.returnType) {
+							const schema = parseTypeToSchema(typingsContent, func.returnType);
+							if (schema) func.returnSchema = schema;
+						}
+					}
+					module.functions.push(...functions);
+				}
+			}
+		}
+	}
+	return modules;
+}
+/**
+* 根据 OpenAPI 配置计算需要扫描的 API 目录集合。
+*
+* 兼容策略：
+* - 当存在 `batch` 时收集每项的 `output`。
+* - 否则尝试使用顶层 `output`。
+* - 以上都不存在时，回退到默认 `src/api` 目录。
+*
+* 注意：配置中的相对路径会被解析到项目根目录下。
+*
+* @param config 解析后的 OpenAPI 配置对象（可能为 null）
+* @param root 项目根目录绝对路径
+* @returns 需要扫描的目录绝对路径数组（去重后）
+*/
+function extractApiDirectories(config, root) {
+	const directories = /* @__PURE__ */ new Set();
+	if (!config) {
+		directories.add(join(root, "src", "api"));
+		return Array.from(directories);
+	}
+	if (config.batch && Array.isArray(config.batch)) {
+		for (const item of config.batch) if (item.output) {
+			const fullPath = join(root, item.output.replace(/^\.\//, ""));
+			directories.add(fullPath);
+		}
+	}
+	if (config.output) {
+		const fullPath = join(root, config.output.replace(/^\.\//, ""));
+		directories.add(fullPath);
+	}
+	if (directories.size === 0) directories.add(join(root, "src", "api"));
+	return Array.from(directories);
+}
+/**
+* 扫描项目并返回 API 概览与配置快照。
+*
+* 执行流程：
+* 1) 在项目根查找并加载 `openapi.config.ts`（若存在）。
+* 2) 基于配置解析出需要扫描的目录（支持 batch/output）。
+* 3) 对每个目录进行递归扫描，收集 API 函数与类型信息。
+*
+* @param root 项目根目录绝对路径
+* @returns {ApiScanResult} 包含配置（可能为 null）与所有模块的扫描结果
+*/
+async function getRequestList(root) {
+	const configPath = await findOpenapiConfig(root);
+	let config = null;
+	if (configPath) config = await loadOpenapiConfig(configPath);
+	const apiDirectories = extractApiDirectories(config, root);
+	const aliasEntries = createAliasResolver(root);
+	const allModules = [];
+	for (const apiDir of apiDirectories) {
+		const modules = await scanApiDirectory(apiDir, root, aliasEntries);
+		allModules.push(...modules);
+	}
+	return {
+		config,
+		modules: allModules
+	};
 }
 
 //#endregion
-//#region src/unocss.ts
-function setupUnoCSSPanel() {
-	addCustomTab({
-		name: "unocss",
-		title: "UnoCSS",
-		icon: `/__unocss/favicon.svg`,
-		view: {
-			type: "iframe",
-			src: "/__unocss/"
-		},
-		category: "advanced"
-	});
+//#region src/server/utils/count-files.ts
+/**
+* 在统计项目文件数量时需要忽略的目录。
+* 这些目录通常体积较大或为构建产物，对健康检查意义不大。
+*/
+const IGNORED_DIRECTORIES = new Set([
+	".git",
+	"dist",
+	"node_modules"
+]);
+/**
+* 递归统计目录下的文件数量。
+*
+* - 忽略符号链接，避免循环引用与跨盘符问题。
+* - 忽略 IGNORED_DIRECTORIES 列表中的目录。
+* - 遇到权限错误/不可读目录时返回 0（宽松模式，不抛错）。
+*
+* 用途：
+* - Devtools 首页/健康检查的一个轻量指标。
+*
+* @param root 目录绝对路径
+* @returns 统计到的文件总数
+*/
+async function countFiles(root) {
+	let total = 0;
+	let entries;
+	try {
+		entries = await readdir(root, {
+			withFileTypes: true,
+			encoding: "utf8"
+		});
+	} catch {
+		return 0;
+	}
+	for (const entry of entries) {
+		const name = String(entry.name);
+		if (entry.isSymbolicLink()) continue;
+		if (entry.isDirectory()) {
+			if (IGNORED_DIRECTORIES.has(name)) continue;
+			total += await countFiles(join(root, name));
+		} else if (entry.isFile()) total += 1;
+	}
+	return total;
 }
 
 //#endregion
-//#region src/index.ts
-function setupDevtoolsPanel() {
-	setupUnoCSSPanel();
-	setupChromeDevtoolsPanel();
+//#region src/server/index.ts
+/**
+* Pubinfo Devtools 的 Vite 插件入口。
+*
+* 能力概览：
+* - 提供一个轻量 UI（iframe）静态资源服务：`/__pubinfo_devtools`。
+* - 提供 devtools 专用的 API：`/__pubinfo_devtools_api`。
+*   - `/` → 返回项目文件数量（用于示例与健康检查）。
+*   - `/api-list` → 返回解析的 OpenAPI 配置与扫描到的 API 函数/类型清单。
+*
+* 注意：本插件默认以 `enforce: 'pre'` 注入，避免被其他中间件拦截。
+* 路由均在开发服务器中间件阶段生效，不影响生产构建输出。
+*
+* 安全说明：这些接口仅用于本地开发环境调试，不应暴露到公网。
+*/
+function pubinfoDevtools() {
+	return {
+		name: "vite-plugin-client",
+		enforce: "pre",
+		configureServer(server) {
+			const baseURL = "__pubinfo_devtools";
+			server.middlewares.use(`/${baseURL}`, sirv(DIR_CLIENT, {
+				single: true,
+				dev: true
+			}));
+			server.middlewares.use(`/${baseURL}_api`, async (req, res, next) => {
+				if (!req.url) return next();
+				if (req.url === "/") {
+					const info = { count: await countFiles(server.config.root) };
+					res.setHeader("Content-Type", "application/json");
+					res.write(JSON.stringify(info));
+					res.end();
+					return;
+				}
+				if (req.url.startsWith("/api-list")) {
+					try {
+						const apiList = await getRequestList(server.config.root);
+						res.setHeader("Content-Type", "application/json");
+						res.write(JSON.stringify(apiList, null, 2));
+					} catch (error) {
+						res.statusCode = 500;
+						res.setHeader("Content-Type", "application/json");
+						res.write(JSON.stringify({
+							error: "Failed to get API list",
+							message: error instanceof Error ? error.message : String(error)
+						}));
+					}
+					res.end();
+					return;
+				}
+				next();
+			});
+		}
+	};
 }
 
 //#endregion
-export { setupDevtoolsPanel };
+export { pubinfoDevtools };

package/dist/panel/index.d.ts

@@ -0,0 +1,10 @@
+//#region src/panel/index.d.ts
+/**
+ * 注册所有内置的 Devtools 面板。
+ *
+ * - UnoCSS：直接复用 Uno 的内置面板（iframe 方式）。
+ * - Server Router：本项目提供的服务路由调试面板。
+ */
+declare function setupDevtoolsPanel(): void;
+//#endregion
+export { setupDevtoolsPanel };