@ubean/scan 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Soybean
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/generator/index.d.ts

@@ -0,0 +1,2 @@
+import { DEFAULT_HEADER_COMMENT, GeneratorOptions, GeneratorResult, GeneratorScanInput, RouteFileGenerator, generateRouteFiles } from "@ubean/vue/generator";
+export { DEFAULT_HEADER_COMMENT, type GeneratorOptions, type GeneratorResult, type GeneratorScanInput, RouteFileGenerator, generateRouteFiles };

package/dist/generator/index.js

@@ -0,0 +1,2 @@
+import { DEFAULT_HEADER_COMMENT, RouteFileGenerator, generateRouteFiles } from "@ubean/vue/generator";
+export { DEFAULT_HEADER_COMMENT, RouteFileGenerator, generateRouteFiles };

package/dist/index.d.ts

@@ -0,0 +1,28 @@
+import { AppEntry, DefineMetaResult, HttpMethod, PageHead, PageMeta, RouteMeta, ScanOptions, ScanPagesOptions, ScanPagesResult, ScanResult, ScannedApiRoute, ScannedAppEntry, ScannedCronTask, ScannedFile, ScannedLayout, ScannedLocale, ScannedMiddleware, ScannedPage, ScannedPageRoute, ScannedPlugin, ScannedQueue, ScannedServerEntry } from "./types.js";
+import { extractDefinePage, extractDefinePageFromCode, extractSlotAndIntercept, filePathToRoute, generateLayoutName, generateRouteName, parseMatchers, stripRouteGroups } from "@ubean/vue/vite";
+import { MatcherFunction, MatcherGuardOptions, clearMatchers, createMatcherGuard, defineMatcher, getMatcher, hasMatcher, listMatcherNames, validateParams } from "@ubean/vue";
+//#region src/scan.d.ts
+declare function scanProject(options: ScanOptions): Promise<ScanResult>;
+//#endregion
+//#region src/detect-exports.d.ts
+interface DetectExportsResult {
+  exports: string[];
+  httpMethods: Lowercase<HttpMethod>[];
+  hasMeta: boolean;
+  fileMeta?: RouteMeta;
+}
+declare function detectHttpExports(filePath: string): Promise<DetectExportsResult>;
+declare function detectHttpExportsFromCode(code: string): DetectExportsResult;
+//#endregion
+//#region src/api-route-id.d.ts
+/**
+ * 服务端专用:生成 API 路由的唯一 ID(`${method}${RouteName}`)。
+ * (页面路由名生成器 `generateRouteName` 所有权在 `@ubean/vue`。)
+ */
+declare function generateApiRouteId(method: string, routePath: string): string;
+//#endregion
+//#region src/define-page.d.ts
+declare function extractDefineMetaFromCode(code: string): DefineMetaResult | null;
+declare function extractDefineMeta(filePath: string): Promise<DefineMetaResult | null>;
+//#endregion
+export { type AppEntry, type DefineMetaResult, type HttpMethod, type MatcherFunction, type MatcherGuardOptions, type PageHead, type PageMeta, type ScanOptions, type ScanPagesOptions, type ScanPagesResult, type ScanResult, type ScannedApiRoute, type ScannedAppEntry, type ScannedCronTask, type ScannedFile, type ScannedLayout, type ScannedLocale, type ScannedMiddleware, type ScannedPage, type ScannedPageRoute, type ScannedPlugin, type ScannedQueue, type ScannedServerEntry, clearMatchers, createMatcherGuard, defineMatcher, detectHttpExports, detectHttpExportsFromCode, extractDefineMeta, extractDefineMetaFromCode, extractDefinePage, extractDefinePageFromCode, extractSlotAndIntercept, filePathToRoute, generateApiRouteId, generateLayoutName, generateRouteName, getMatcher, hasMatcher, listMatcherNames, parseMatchers, scanProject, stripRouteGroups, validateParams };

package/dist/index.js

@@ -0,0 +1,558 @@
+import { GLOB_SCAN_PATTERN, HTTP_METHODS } from "./types.js";
+import { readFile } from "node:fs/promises";
+import { getLogger } from "@ubean/logger";
+import { extractCallObject, extractDefinePage, extractDefinePageFromCode, extractSlotAndIntercept, filePathToRoute, filePathToRoute as filePathToRoute$1, generateLayoutName, generateRouteName, generateRouteName as generateRouteName$1, parseMatchers, scanPages, stripRouteGroups } from "@ubean/vue/vite";
+import { basename, dirname, extname, isAbsolute, join, relative } from "pathe";
+import { glob } from "tinyglobby";
+import { clearMatchers, createMatcherGuard, defineMatcher, getMatcher, hasMatcher, listMatcherNames, validateParams } from "@ubean/vue";
+//#region src/detect-exports.ts
+const EXPORT_NAMED_REGEX = /export\s+(?:async\s+)?(?:function\s+|const\s+|let\s+|var\s+)?(\w+)/g;
+const EXPORT_LIST_REGEX = /export\s*\{([^}]+)\}/g;
+const EXPORT_DEFINE_META_REGEX = /defineHandlerMeta\s*\(/;
+const EXPORT_CONST_META_REGEX = /export\s+const\s+meta\s*=\s*(\{[\s\S]*?\})(?:\s*;|\s*$)/m;
+const META_REQUIRES_AUTH_REGEX = /requiresAuth\s*:\s*(true|false)/;
+async function detectHttpExports(filePath) {
+	return detectHttpExportsFromCode(await readFile(filePath, "utf-8"));
+}
+function detectHttpExportsFromCode(code) {
+	const exports = /* @__PURE__ */ new Set();
+	const httpMethods = [];
+	let match;
+	EXPORT_NAMED_REGEX.lastIndex = 0;
+	while ((match = EXPORT_NAMED_REGEX.exec(code)) !== null) {
+		const name = match[1];
+		exports.add(name);
+		const lower = name.toLowerCase();
+		if (HTTP_METHODS.includes(name) && !httpMethods.includes(lower)) httpMethods.push(lower);
+	}
+	EXPORT_LIST_REGEX.lastIndex = 0;
+	while ((match = EXPORT_LIST_REGEX.exec(code)) !== null) {
+		const list = match[1];
+		for (const item of list.split(",")) {
+			const name = item.trim().split(/\s+as\s+/).pop()?.trim();
+			if (name) {
+				exports.add(name);
+				const upper = name.toUpperCase();
+				const lower = name.toLowerCase();
+				if (HTTP_METHODS.includes(upper) && !httpMethods.includes(lower)) httpMethods.push(lower);
+			}
+		}
+	}
+	const hasDefineMeta = EXPORT_DEFINE_META_REGEX.test(code);
+	const fileMeta = extractFileMeta(code);
+	const hasMeta = hasDefineMeta || !!fileMeta;
+	return {
+		exports: [...exports],
+		httpMethods,
+		hasMeta,
+		fileMeta
+	};
+}
+function extractFileMeta(code) {
+	const match = code.match(EXPORT_CONST_META_REGEX);
+	if (!match) return void 0;
+	const metaBlock = match[1];
+	const meta = {};
+	const requiresAuthMatch = metaBlock.match(META_REQUIRES_AUTH_REGEX);
+	if (requiresAuthMatch) meta.requiresAuth = requiresAuthMatch[1] === "true";
+	return Object.keys(meta).length > 0 ? meta : void 0;
+}
+//#endregion
+//#region src/scan.ts
+/**
+* 聚合层项目扫描:`@ubean/scan` = 服务端目录扫描(API 路由/中间件/
+* 插件/crons/queues/locales/entries)+ 页面路由(委托 `@ubean/vue` 的
+* 页面扫描器 —— 页面路由唯一所有者)。
+*
+* 页面/布局扫描、reuse cache 继承、markdown frontmatter、页面级 head、
+* 特殊页(404/loading/error)、并行/拦截路由、`[param=matcher]` 语法均
+* 在 `@ubean/vue/vite` 的 `scanPages` 中实现;本文件只做聚合与默认值
+* (框架模式:markdown 开启、head 开启,保证 SSR `pageObj.head` 链路可用)。
+*/
+const logger = getLogger("routing");
+const DEFAULT_DIRS = {
+	routes: "routes",
+	middleware: "middleware",
+	pages: "pages",
+	layouts: "layouts",
+	plugins: "plugins",
+	crons: "crons",
+	queues: "queues",
+	locales: "locales"
+};
+/**
+* Normalize a `string | string[]` dir entry into `string[]`. Falsy values
+* fall back to the provided default so callers always receive a non-empty
+* list. Empty arrays are also replaced with the default to keep downstream
+* globbing simple.
+*/
+function normalizeDirs(value, fallback) {
+	if (value === void 0 || value === null || value === "") return [fallback];
+	if (Array.isArray(value)) {
+		const filtered = value.filter((d) => typeof d === "string" && d.length > 0);
+		return filtered.length > 0 ? filtered : [fallback];
+	}
+	return [value];
+}
+function splitOrderPrefix(name) {
+	const match = name.match(/^(\d+)\.(.+)$/);
+	if (match) return {
+		order: Number(match[1]),
+		cleanName: match[2]
+	};
+	return {
+		order: 0,
+		cleanName: name
+	};
+}
+function toPosixPath(p) {
+	return p.replace(/\\/g, "/");
+}
+async function scanProject(options) {
+	const dirs = {
+		...DEFAULT_DIRS,
+		...options.dirs
+	};
+	const ignore = options.ignore || [
+		"**/*.test.*",
+		"**/*.spec.*",
+		"**/_*",
+		"**/*.d.ts"
+	];
+	const srcDir = isAbsolute(options.srcDir) ? options.srcDir : join(options.cwd, options.srcDir);
+	const markdown = options.markdown === void 0 ? true : options.markdown;
+	const head = options.head === void 0 ? true : options.head;
+	const [apiRoutes, middlewares, pagesResult, plugins, crons, queues, locales, appEntry, serverEntry] = await Promise.all([
+		scanApiRoutes(srcDir, dirs.routes, ignore),
+		scanMiddlewares(srcDir, dirs.middleware, ignore),
+		scanPages({
+			cwd: options.cwd,
+			srcDir,
+			pagesDir: dirs.pages,
+			layoutsDir: dirs.layouts,
+			ignore: options.ignore,
+			markdown,
+			head
+		}),
+		scanPlugins(srcDir, dirs.plugins, ignore),
+		scanCrons(srcDir, dirs.crons, ignore),
+		scanQueues(srcDir, dirs.queues, ignore),
+		scanLocales(srcDir, dirs.locales, ignore),
+		scanAppEntry(srcDir),
+		scanServerEntry(srcDir)
+	]);
+	const { pages, layouts, notFoundPage, loadingPage, errorPage } = pagesResult;
+	return {
+		apiRoutes,
+		middlewares,
+		pages,
+		layouts,
+		plugins,
+		crons,
+		queues,
+		locales,
+		defaultLocale: locales.find((l) => l.isDefault)?.code || locales[0]?.code,
+		appEntry,
+		serverEntry,
+		notFoundPage,
+		loadingPage,
+		errorPage
+	};
+}
+async function scanApiRoutes(srcDir, dirName, ignore) {
+	const dirNames = normalizeDirs(dirName, "routes");
+	const routes = [];
+	for (const single of dirNames) {
+		const dir = join(srcDir, single);
+		const files = await glob(GLOB_SCAN_PATTERN, {
+			cwd: dir,
+			dot: true,
+			ignore: [
+				...ignore,
+				"**/*.vue",
+				"**/_*"
+			],
+			absolute: true
+		}).catch(() => []);
+		for (const fullPath of files.sort()) {
+			const relativePath = toPosixPath(relative(dir, fullPath));
+			const base = basename(relativePath, extname(relativePath));
+			const dirPart = dirname(relativePath) === "." ? "" : dirname(relativePath);
+			const fileBase = dirPart ? `${dirPart}/${base}` : base;
+			const parsed = filePathToRoute$1(fileBase);
+			const detected = await detectHttpExports(fullPath).catch(() => ({
+				exports: [],
+				httpMethods: [],
+				hasMeta: false,
+				fileMeta: void 0
+			}));
+			const methods = detected.httpMethods.length > 0 ? detected.httpMethods : parsed.method ? [parsed.method.toLowerCase()] : [];
+			for (const method of methods.length > 0 ? methods : HTTP_METHODS.map((m) => m.toLowerCase())) routes.push({
+				fullPath,
+				relativePath,
+				dirname: dirname(relativePath),
+				basename: basename(relativePath),
+				route: parsed.route,
+				method,
+				env: parsed.env,
+				exports: detected.exports,
+				hasMeta: detected.hasMeta,
+				fileMeta: detected.fileMeta,
+				matchers: parsed.matchers
+			});
+		}
+	}
+	return routes;
+}
+async function scanMiddlewares(srcDir, dirName, ignore) {
+	const dirNames = normalizeDirs(dirName, "middleware");
+	const results = [];
+	for (const single of dirNames) {
+		const dir = join(srcDir, single);
+		const files = await glob(GLOB_SCAN_PATTERN, {
+			cwd: dir,
+			dot: true,
+			ignore: [
+				...ignore,
+				"**/*.vue",
+				"**/index.*",
+				"**/_*"
+			],
+			absolute: true
+		}).catch(() => []);
+		for (const fullPath of files.sort()) {
+			const relativePath = toPosixPath(relative(dir, fullPath));
+			const { order, cleanName } = splitOrderPrefix(basename(relativePath, extname(relativePath)));
+			results.push({
+				fullPath,
+				relativePath,
+				dirname: dirname(relativePath),
+				basename: basename(relativePath),
+				order,
+				global: cleanName === "global" || cleanName.startsWith("global.")
+			});
+		}
+	}
+	return results;
+}
+async function scanPlugins(srcDir, dirName, ignore) {
+	const dirNames = normalizeDirs(dirName, "plugins");
+	const results = [];
+	for (const single of dirNames) {
+		const dir = join(srcDir, single);
+		const files = await glob(GLOB_SCAN_PATTERN, {
+			cwd: dir,
+			dot: true,
+			ignore: [
+				...ignore,
+				"**/*.vue",
+				"**/_*"
+			],
+			absolute: true
+		}).catch(() => []);
+		for (const fullPath of files.sort()) {
+			const relativePath = toPosixPath(relative(dir, fullPath));
+			const { order } = splitOrderPrefix(basename(relativePath, extname(relativePath)));
+			results.push({
+				fullPath,
+				relativePath,
+				dirname: dirname(relativePath),
+				basename: basename(relativePath),
+				order
+			});
+		}
+	}
+	return results;
+}
+const APP_EXTENSIONS = [
+	"ts",
+	"js",
+	"mjs",
+	"mts"
+];
+async function scanCrons(srcDir, dirName, ignore) {
+	const dirNames = normalizeDirs(dirName, "crons");
+	const results = [];
+	for (const single of dirNames) {
+		const dir = join(srcDir, single);
+		const files = await glob(GLOB_SCAN_PATTERN, {
+			cwd: dir,
+			dot: true,
+			ignore: [
+				...ignore,
+				"**/*.vue",
+				"**/_*"
+			],
+			absolute: true
+		}).catch(() => []);
+		for (const fullPath of files.sort()) {
+			const relativePath = toPosixPath(relative(dir, fullPath));
+			const { cleanName } = splitOrderPrefix(basename(relativePath, extname(relativePath)));
+			results.push({
+				fullPath,
+				relativePath,
+				dirname: dirname(relativePath),
+				basename: basename(relativePath),
+				name: cleanName
+			});
+		}
+	}
+	return results;
+}
+async function scanQueues(srcDir, dirName, ignore) {
+	const dirNames = normalizeDirs(dirName, "queues");
+	const results = [];
+	for (const single of dirNames) {
+		const dir = join(srcDir, single);
+		const files = await glob(GLOB_SCAN_PATTERN, {
+			cwd: dir,
+			dot: true,
+			ignore: [
+				...ignore,
+				"**/*.vue",
+				"**/_*"
+			],
+			absolute: true
+		}).catch(() => []);
+		for (const fullPath of files.sort()) {
+			const relativePath = toPosixPath(relative(dir, fullPath));
+			const { cleanName } = splitOrderPrefix(basename(relativePath, extname(relativePath)));
+			results.push({
+				fullPath,
+				relativePath,
+				dirname: dirname(relativePath),
+				basename: basename(relativePath),
+				name: cleanName
+			});
+		}
+	}
+	return results;
+}
+const LOCALE_GLOB_PATTERN = "**/*.{json,json5,yaml,yml,js,mjs,cjs,ts,mts,cts}";
+function parseSimpleYaml(content) {
+	const result = {};
+	const lines = content.split("\n");
+	let currentObj = result;
+	const stack = [];
+	for (const line of lines) {
+		const trimmed = line.replace(/#.*$/, "").trimEnd();
+		if (!trimmed || trimmed.startsWith("#")) continue;
+		const indent = line.length - line.trimStart().length;
+		const match = trimmed.match(/^([\w.-]+)\s*:\s*(.*)$/);
+		if (!match) continue;
+		const [, key, value] = match;
+		while (stack.length > 0 && stack[stack.length - 1].indent >= indent) stack.pop();
+		currentObj = stack.length > 0 ? stack[stack.length - 1].obj : result;
+		if (value === "" || value === void 0) {
+			const newObj = {};
+			currentObj[key] = newObj;
+			stack.push({
+				obj: newObj,
+				indent
+			});
+			currentObj = newObj;
+		} else {
+			let parsed = value;
+			if (value === "true") parsed = true;
+			else if (value === "false") parsed = false;
+			else if (value === "null") parsed = null;
+			else if (/^-?\d+$/.test(value)) parsed = Number.parseInt(value, 10);
+			else if (/^-?\d+\.\d+$/.test(value)) parsed = Number.parseFloat(value);
+			else if (value.startsWith("\"") && value.endsWith("\"") || value.startsWith("'") && value.endsWith("'")) parsed = value.slice(1, -1);
+			currentObj[key] = parsed;
+		}
+	}
+	return result;
+}
+async function loadLocaleFile(fullPath, ext) {
+	const extract = (data) => {
+		const isWrapper = (typeof data.name === "string" || data.dir === "ltr" || data.dir === "rtl" || typeof data.isDefault === "boolean") && typeof data.messages === "object" && data.messages !== null;
+		return {
+			messages: isWrapper ? data.messages : data,
+			meta: isWrapper ? {
+				name: data.name,
+				dir: data.dir,
+				isDefault: data.isDefault
+			} : void 0
+		};
+	};
+	if (ext === ".json" || ext === ".json5") {
+		const content = await readFile(fullPath, "utf-8");
+		return extract(JSON.parse(content));
+	}
+	if (ext === ".yaml" || ext === ".yml") return extract(parseSimpleYaml(await readFile(fullPath, "utf-8")));
+	if (ext === ".js" || ext === ".mjs" || ext === ".cjs" || ext === ".ts" || ext === ".mts" || ext === ".cts") {
+		const mod = await import(
+			/* @vite-ignore */
+			fullPath
+).catch(() => null);
+		if (mod) return extract(mod.default || mod);
+	}
+	return { messages: {} };
+}
+async function scanLocales(srcDir, dirName, ignore) {
+	const dirNames = normalizeDirs(dirName, "locales");
+	const locales = [];
+	const seenFullPaths = /* @__PURE__ */ new Set();
+	for (const single of dirNames) {
+		const dir = join(srcDir, single);
+		const files = await glob(LOCALE_GLOB_PATTERN, {
+			cwd: dir,
+			dot: true,
+			ignore: [
+				...ignore,
+				"**/*.vue",
+				"**/_*"
+			],
+			absolute: true
+		}).catch(() => []);
+		for (const fullPath of files.sort()) {
+			if (seenFullPaths.has(fullPath)) continue;
+			seenFullPaths.add(fullPath);
+			const relativePath = toPosixPath(relative(dir, fullPath));
+			const ext = extname(relativePath);
+			const base = basename(relativePath, ext);
+			const { order: _order, cleanName: code } = splitOrderPrefix(base);
+			const dirPart = dirname(relativePath) === "." ? "" : dirname(relativePath);
+			let namespace;
+			let finalCode = code;
+			let isDefault = code === "default" || base.startsWith("default.");
+			if (dirPart) {
+				const dirParts = dirPart.split("/");
+				const isIndexFile = code === "index";
+				finalCode = dirParts[0];
+				const nsParts = [];
+				nsParts.push(...dirParts.slice(1));
+				if (!isIndexFile) nsParts.push(code);
+				if (nsParts.length > 0) namespace = nsParts.join(".");
+			}
+			let name;
+			let dirVal;
+			try {
+				const { meta } = await loadLocaleFile(fullPath, ext);
+				if (meta?.name) name = meta.name;
+				if (meta?.dir) dirVal = meta.dir;
+				if (meta?.isDefault) isDefault = true;
+			} catch {
+				logger.warn(`Failed to parse locale file: ${relativePath}`);
+			}
+			if (isDefault && finalCode === "default") finalCode = "en";
+			locales.push({
+				fullPath,
+				relativePath,
+				dirname: dirname(relativePath),
+				basename: basename(relativePath),
+				code: finalCode,
+				namespace,
+				isDefault,
+				name,
+				dir: dirVal
+			});
+		}
+	}
+	return locales;
+}
+async function scanAppEntry(srcDir) {
+	const result = {
+		shared: { exists: false },
+		server: { exists: false },
+		client: { exists: false }
+	};
+	const findEntry = async (baseName) => {
+		for (const ext of APP_EXTENSIONS) {
+			const fullPath = join(srcDir, `${baseName}.${ext}`);
+			if (await fileExists(fullPath)) return {
+				exists: true,
+				fullPath,
+				relativePath: `${baseName}.${ext}`
+			};
+		}
+		return { exists: false };
+	};
+	const [shared, server, client] = await Promise.all([
+		findEntry("app"),
+		findEntry("app.server"),
+		findEntry("app.client")
+	]);
+	result.shared = shared;
+	result.server = server;
+	result.client = client;
+	return result;
+}
+async function scanServerEntry(srcDir) {
+	const result = {
+		shared: { exists: false },
+		dev: { exists: false },
+		prod: { exists: false }
+	};
+	const findEntry = async (baseName) => {
+		for (const ext of APP_EXTENSIONS) {
+			const fullPath = join(srcDir, `${baseName}.${ext}`);
+			if (await fileExists(fullPath)) return {
+				exists: true,
+				fullPath,
+				relativePath: `${baseName}.${ext}`
+			};
+		}
+		return { exists: false };
+	};
+	const [shared, dev, prod] = await Promise.all([
+		findEntry("server"),
+		findEntry("server.dev"),
+		findEntry("server.prod")
+	]);
+	result.shared = shared;
+	result.dev = dev;
+	result.prod = prod;
+	return result;
+}
+async function fileExists(path) {
+	const { existsSync } = await import("node:fs");
+	return existsSync(path);
+}
+//#endregion
+//#region src/api-route-id.ts
+/**
+* 服务端专用:生成 API 路由的唯一 ID(`${method}${RouteName}`)。
+* (页面路由名生成器 `generateRouteName` 所有权在 `@ubean/vue`。)
+*/
+function generateApiRouteId(method, routePath) {
+	const routeName = generateRouteName$1(routePath);
+	return `${method.toLowerCase()}${routeName}`;
+}
+//#endregion
+//#region src/define-page.ts
+function extractScriptContent(code) {
+	if (!code.includes("<script")) return code;
+	let scriptContent = "";
+	const scriptRegex = /<script([^>]*)>([\s\S]*?)<\/script>/g;
+	let match;
+	while ((match = scriptRegex.exec(code)) !== null) {
+		const attrs = match[1] || "";
+		const content = match[2] || "";
+		if (attrs.includes("setup")) return content;
+		scriptContent += `${content}\n`;
+	}
+	return scriptContent || null;
+}
+function extractDefineMetaFromCode(code) {
+	const scriptContent = extractScriptContent(code);
+	if (!scriptContent) return null;
+	const parsed = extractCallObject(scriptContent, "defineHandlerMeta");
+	if (!parsed) return null;
+	const result = {};
+	if (typeof parsed.requiresAuth === "boolean") result.requiresAuth = parsed.requiresAuth;
+	if (parsed.meta && typeof parsed.meta === "object") result.meta = parsed.meta;
+	else {
+		const knownKeys = /* @__PURE__ */ new Set(["requiresAuth", "meta"]);
+		const extra = {};
+		for (const [key, val] of Object.entries(parsed)) if (!knownKeys.has(key)) extra[key] = val;
+		if (Object.keys(extra).length > 0) result.meta = extra;
+	}
+	return result;
+}
+async function extractDefineMeta(filePath) {
+	return extractDefineMetaFromCode(await readFile(filePath, "utf-8"));
+}
+//#endregion
+export { clearMatchers, createMatcherGuard, defineMatcher, detectHttpExports, detectHttpExportsFromCode, extractDefineMeta, extractDefineMetaFromCode, extractDefinePage, extractDefinePageFromCode, extractSlotAndIntercept, filePathToRoute, generateApiRouteId, generateLayoutName, generateRouteName, getMatcher, hasMatcher, listMatcherNames, parseMatchers, scanProject, stripRouteGroups, validateParams };

package/dist/types.d.ts

@@ -0,0 +1,136 @@
+import { PageHead, PageMeta, ScanPagesOptions, ScanPagesResult, ScannedLayout, ScannedPage, ScannedPage as ScannedPageRoute } from "@ubean/vue";
+import { RouteMeta, RouteMeta as RouteMeta$1 } from "@ubean/shared";
+//#region src/types.d.ts
+/**
+ * HTTP methods supported by ubean API routes.
+ * Aligned with Hono's built-in methods (excludes TRACE).
+ */
+declare const HTTP_METHODS: readonly ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"];
+type HttpMethod = (typeof HTTP_METHODS)[number];
+interface ScannedFile {
+  fullPath: string;
+  relativePath: string;
+  dirname: string;
+  basename: string;
+}
+interface ScannedApiRoute extends ScannedFile {
+  route: string;
+  method?: HttpMethod | Lowercase<HttpMethod>;
+  env?: 'dev' | 'prod' | 'prerender';
+  exports: string[];
+  hasMeta: boolean;
+  fileMeta?: RouteMeta$1;
+  /**
+   * 路由参数 → matcher 名称映射。
+   *
+   * 由文件路由 `[param=matcher]` 语法解析得到,例如 `routes/api/users/[id=numeric].ts`
+   * → `{ id: 'numeric' }`。运行时 router 在匹配到该路由后,调用对应名称的 matcher
+   * 函数校验参数值,失败则视为不匹配(返回 404,让 Hono 继续匹配下一候选路由)。
+   *
+   * 与 `ScannedPage.matchers` 同义,但作用于 API 路由。
+   */
+  matchers?: Record<string, string>;
+}
+interface ScannedMiddleware extends ScannedFile {
+  order: number;
+  global: boolean;
+}
+interface ScannedPlugin extends ScannedFile {
+  order: number;
+}
+interface ScannedCronTask extends ScannedFile {
+  name: string;
+}
+interface ScannedQueue extends ScannedFile {
+  name: string;
+}
+interface ScannedLocale extends ScannedFile {
+  code: string;
+  namespace?: string;
+  isDefault?: boolean;
+  name?: string;
+  dir?: 'ltr' | 'rtl';
+}
+interface AppEntry {
+  exists: boolean;
+  fullPath?: string;
+  relativePath?: string;
+}
+interface ScannedAppEntry {
+  shared: AppEntry;
+  server: AppEntry;
+  client: AppEntry;
+}
+interface ScannedServerEntry {
+  shared: AppEntry;
+  dev: AppEntry;
+  prod: AppEntry;
+}
+interface ScanOptions {
+  cwd: string;
+  srcDir: string;
+  dirs?: {
+    routes?: string | string[];
+    middleware?: string | string[];
+    pages?: string | string[];
+    layouts?: string | string[];
+    plugins?: string | string[];
+    crons?: string | string[];
+    queues?: string | string[];
+    locales?: string | string[];
+  };
+  ignore?: string[];
+  /**
+   * 页面 markdown 支持(委托给 `@ubean/vue` 扫描器)。
+   * 框架模式默认开启(`true` = `.md` + `.mdx`);传 `'md'` / `'mdx'` 精细控制。
+   */
+  markdown?: boolean | 'mdx' | 'md';
+  /**
+   * 页面级 head 支持(委托给 `@ubean/vue` 扫描器)。
+   * 框架模式(SSR)默认开启(`true`),保证 `pageObj.head` 链路可用。
+   */
+  head?: boolean;
+}
+interface ScanResult {
+  apiRoutes: ScannedApiRoute[];
+  middlewares: ScannedMiddleware[];
+  pages: import('@ubean/vue').ScannedPage[];
+  layouts: import('@ubean/vue').ScannedLayout[];
+  plugins: ScannedPlugin[];
+  crons: ScannedCronTask[];
+  queues: ScannedQueue[];
+  locales: ScannedLocale[];
+  defaultLocale?: string;
+  appEntry: ScannedAppEntry;
+  serverEntry: ScannedServerEntry;
+  /**
+   * `pages/404.vue`(或 `.tsx`/`.md`)自动检测的 404 页面。
+   * 不作为常规路由注册,而是作为 Vue Router 的 catch-all 路由
+   * `/:pathMatch(.*)*` 和 Hono 的兜底页面处理器。
+   * `undefined` 表示未找到 404 页面文件。
+   */
+  notFoundPage?: import('@ubean/vue').ScannedPage;
+  /**
+   * `pages/loading.vue`(或 `.ts`/`.md`)自动检测的加载组件。
+   * 不作为路由注册,而是作为 `<Suspense>` 的 fallback 组件,
+   * 在 SPA 导航懒加载页面组件时显示。
+   * `undefined` 表示未找到 loading 页面文件。
+   */
+  loadingPage?: import('@ubean/vue').ScannedPage;
+  /**
+   * `pages/error.vue`(或 `.ts`/`.md`)自动检测的错误兜底组件。
+   * 不作为路由注册,而是作为渲染错误边界(ErrorBoundary)组件,
+   * 当页面组件渲染、异步解析或 setup 抛出错误时显示。
+   * `undefined` 表示未找到 error 页面文件。
+   */
+  errorPage?: import('@ubean/vue').ScannedPage;
+}
+declare const GLOB_SCAN_PATTERN = "**/*.{js,mjs,cjs,ts,mts,cts,tsx,jsx}";
+declare const GLOB_VUE_PATTERN = "**/*.{vue,ts,md,mdx}";
+declare const GLOB_LAYOUT_PATTERN = "**/*.{vue,ts}";
+interface DefineMetaResult {
+  meta?: Record<string, unknown>;
+  requiresAuth?: boolean;
+}
+//#endregion
+export { AppEntry, DefineMetaResult, GLOB_LAYOUT_PATTERN, GLOB_SCAN_PATTERN, GLOB_VUE_PATTERN, HTTP_METHODS, HttpMethod, type PageHead, type PageMeta, type RouteMeta, ScanOptions, type ScanPagesOptions, type ScanPagesResult, ScanResult, ScannedApiRoute, ScannedAppEntry, ScannedCronTask, ScannedFile, type ScannedLayout, ScannedLocale, ScannedMiddleware, type ScannedPage, type ScannedPageRoute, ScannedPlugin, ScannedQueue, ScannedServerEntry };

package/dist/types.js

@@ -0,0 +1,19 @@
+//#region src/types.ts
+/**
+* HTTP methods supported by ubean API routes.
+* Aligned with Hono's built-in methods (excludes TRACE).
+*/
+const HTTP_METHODS = [
+	"GET",
+	"POST",
+	"PUT",
+	"PATCH",
+	"DELETE",
+	"HEAD",
+	"OPTIONS"
+];
+const GLOB_SCAN_PATTERN = "**/*.{js,mjs,cjs,ts,mts,cts,tsx,jsx}";
+const GLOB_VUE_PATTERN = "**/*.{vue,ts,md,mdx}";
+const GLOB_LAYOUT_PATTERN = "**/*.{vue,ts}";
+//#endregion
+export { GLOB_LAYOUT_PATTERN, GLOB_SCAN_PATTERN, GLOB_VUE_PATTERN, HTTP_METHODS };

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@ubean/scan",
+  "version": "0.2.0",
+  "description": "Project scanner & route metadata for ubean — server-side directory scanning (API routes, middleware, plugins, crons, queues, locales, entries) plus page scanning delegated to @ubean/vue",
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./generator": {
+      "types": "./dist/generator/index.d.ts",
+      "import": "./dist/generator/index.js"
+    },
+    "./types": {
+      "types": "./dist/types.d.ts",
+      "import": "./dist/types.js"
+    }
+  },
+  "dependencies": {
+    "pathe": "^2.0.3",
+    "tinyglobby": "^0.2.17",
+    "@ubean/logger": "0.2.0",
+    "@ubean/shared": "0.2.0",
+    "@ubean/vue": "0.2.0"
+  },
+  "devDependencies": {
+    "@types/node": "^26.2.0",
+    "typescript": "7.0.2",
+    "vite-plus": "0.2.9",
+    "vue": "^3.5.41",
+    "vue-router": "^5.2.0",
+    "@ubean/markdown": "0.2.0"
+  },
+  "peerDependencies": {
+    "vue-router": "^4.0.0"
+  },
+  "peerDependenciesMeta": {
+    "vue-router": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "build": "vp pack",
+    "dev": "vp pack --watch",
+    "test": "vp test",
+    "typecheck": "tsc --noEmit --skipLibCheck"
+  }
+}