@ubean/vue 0.2.0

package/dist/generator/index.js

@@ -0,0 +1,369 @@
+//#region src/generator/index.ts
+const DEFAULT_HEADER_COMMENT = "// @generated by @ubean/vue/generator — do not edit manually.\n// This file is regenerated on every dev start / build.";
+async function generateRouteFiles(scan, options) {
+	return new RouteFileGenerator(options).generate(scan);
+}
+var RouteFileGenerator = class {
+	opts;
+	constructor(options) {
+		const dtsPath = options.dtsPath ?? joinPosix(options.outDir, "typed-router.d.ts");
+		this.opts = {
+			cwd: options.cwd,
+			srcDir: options.srcDir ?? joinPosix(options.cwd, "src"),
+			outDir: options.outDir,
+			dtsPath,
+			generateRoutes: options.generateRoutes ?? true,
+			generateImports: options.generateImports ?? true,
+			generateDts: options.generateDts ?? true,
+			routeLazy: options.routeLazy ?? true,
+			layoutLazy: options.layoutLazy ?? true,
+			headerComment: options.headerComment ?? "// @generated by @ubean/vue/generator — do not edit manually.\n// This file is regenerated on every dev start / build.",
+			getRouteMeta: options.getRouteMeta,
+			getImportPath: options.getImportPath,
+			getLayoutImportPath: options.getLayoutImportPath
+		};
+	}
+	async generate(scan) {
+		const { cwd, outDir, dtsPath, generateRoutes, generateImports, generateDts } = this.opts;
+		const routesPath = generateRoutes ? joinPosix(outDir, "routes.ts") : void 0;
+		const importsPath = generateImports ? joinPosix(outDir, "imports.ts") : void 0;
+		const finalDtsPath = generateDts ? dtsPath : void 0;
+		await Promise.all([
+			routesPath ? writeFile(resolvePath(cwd, routesPath), this.renderRoutesFile(scan)) : null,
+			importsPath ? writeFile(resolvePath(cwd, importsPath), this.renderImportsFile(scan)) : null,
+			finalDtsPath ? writeFile(resolvePath(cwd, finalDtsPath), this.renderDtsFile(scan)) : null
+		]);
+		return {
+			routesPath,
+			importsPath,
+			dtsPath: finalDtsPath,
+			routeCount: scan.pages.length,
+			layoutCount: scan.layouts.length
+		};
+	}
+	renderRoutesFile(scan) {
+		return `${this.opts.headerComment}
+
+import type { RouteRecord } from './imports';
+
+export const routes: RouteRecord[] = [
+${scan.pages.map((p) => this.renderRouteRecord(p)).join(",\n")}
+];
+`;
+	}
+	renderRouteRecord(page) {
+		const parts = [];
+		parts.push(`    name: ${JSON.stringify(page.name)}`);
+		parts.push(`    path: ${JSON.stringify(page.route)}`);
+		const componentKey = page.isReuse && page.reuseTarget ? page.reuseTarget : page.name;
+		parts.push(`    component: ${JSON.stringify(componentKey)}`);
+		if (page.layout !== void 0) {
+			let layoutVal;
+			if (page.layout === false) layoutVal = "false";
+			else if (Array.isArray(page.layout)) layoutVal = JSON.stringify(page.layout);
+			else layoutVal = JSON.stringify(page.layout);
+			parts.push(`    layout: ${layoutVal}`);
+		}
+		if (page.isReuse) parts.push(`    reuse: true`);
+		const meta = this.computeMeta(page);
+		if (meta && Object.keys(meta).length > 0) parts.push(`    meta: ${JSON.stringify(meta)}`);
+		if (page.pageMeta?.cache === true) parts.push(`    cache: true`);
+		if (page.pageMeta?.requiresAuth === true) parts.push(`    requiresAuth: true`);
+		return `  {\n${parts.join(",\n")}\n  }`;
+	}
+	computeMeta(page) {
+		const base = page.pageMeta?.meta ?? {};
+		const merged = {
+			...this.opts.getRouteMeta?.(page) ?? {},
+			...base
+		};
+		if (page.matchers && Object.keys(page.matchers).length > 0) merged.matchers = page.matchers;
+		return Object.keys(merged).length > 0 ? merged : null;
+	}
+	renderImportsFile(scan) {
+		const header = this.opts.headerComment;
+		const layouts = scan.layouts.map((l) => this.renderLayoutImport(l)).join(",\n");
+		const views = scan.pages.filter((p) => !p.isReuse).map((p) => this.renderViewImport(p)).join(",\n");
+		const layoutType = scan.layouts.length > 0 ? `'${scan.layouts.map((l) => l.name).join("' | '")}'` : "string";
+		const filePages = scan.pages.filter((p) => !p.isReuse);
+		const reusePages = scan.pages.filter((p) => p.isReuse);
+		return `${header}
+
+export type LayoutKey = ${layoutType};
+
+/**
+ * Route keys that have a corresponding source file (\`.vue\` / \`.md\`).
+ * Excludes reuse routes and builtin routes.
+ *
+ * The \`views\` map is keyed by this type — \`views[RouteFileKey]\` resolves
+ * to the actual component loader.
+ */
+export type RouteFileKey = ${filePages.length > 0 ? `'${filePages.map((p) => p.name).join("' | '")}'` : "never"};
+
+/**
+ * Route keys declared via \`.reuse.ts\` / \`.reuse.js\` metadata files.
+ * They reference another route's component via \`reuseTarget\`.
+ */
+export type RouteReuseKey = ${reusePages.length > 0 ? `'${reusePages.map((p) => p.name).join("' | '")}'` : "never"};
+
+/**
+ * Builtin route keys (framework-provided, e.g. \`root\` / \`not_found\`).
+ * Currently unused — reserved for future builtin pages.
+ */
+export type BuiltinRouteKey = never;
+
+/**
+ * All page route names. Union of {@link RouteFileKey}, {@link RouteReuseKey}
+ * and {@link BuiltinRouteKey}.
+ */
+export type RouteKey = ${scan.pages.length > 0 ? `'${scan.pages.map((p) => p.name).join("' | '")}'` : "never"};
+
+export type Lazy<T> = () => Promise<T>;
+export type RawRouteComponent = import('vue').Component | Lazy<import('vue').Component>;
+
+export interface RouteRecord {
+  name: RouteKey;
+  path: string;
+  /**
+   * Key into the \`views\` map — resolve the actual component via
+   * \`views[route.component]\`.
+   *
+   * For reuse routes, this is the \`reuseTarget\`'s \`RouteFileKey\`
+   * (not the reuse route's own name), so the same component is reused.
+   */
+  component: RouteFileKey;
+  layout?: LayoutKey | LayoutKey[] | false;
+  reuse?: boolean;
+  meta?: Record<string, unknown>;
+  cache?: boolean;
+  requiresAuth?: boolean;
+}
+
+export const layouts: Record<LayoutKey, RawRouteComponent> = {
+${layouts}
+};
+
+export const views: Record<RouteFileKey, RawRouteComponent> = {
+${views}
+};
+`;
+	}
+	renderLayoutImport(layout) {
+		const importPath = this.opts.getLayoutImportPath?.(layout) ?? defaultLayoutImportPath(layout, this.opts.srcDir);
+		if (typeof this.opts.layoutLazy === "function" ? this.opts.layoutLazy(layout) : this.opts.layoutLazy) return `  ${layout.name}: () => import(${JSON.stringify(importPath)})`;
+		const importName = `__layout_${layout.name}`;
+		return `  ${layout.name}: ${importName}, // import ${importName} from ${JSON.stringify(importPath)}`;
+	}
+	renderViewImport(page) {
+		const importPath = this.opts.getImportPath?.(page) ?? defaultPageImportPath(page, this.opts.srcDir);
+		if (typeof this.opts.routeLazy === "function" ? this.opts.routeLazy(page) : this.opts.routeLazy) return `  ${page.name}: () => import(${JSON.stringify(importPath)})`;
+		return `  ${page.name}: ${page.name}, // import ${page.name} from ${JSON.stringify(importPath)}`;
+	}
+	renderDtsFile(scan) {
+		const header = this.opts.headerComment;
+		const pathMapEntries = scan.pages.length > 0 ? scan.pages.map((p) => `    "${p.name}": "${p.route}";`).join("\n") : "    // (no pages scanned)";
+		const reuseRoutes = scan.pages.filter((p) => p.isReuse);
+		const reuseKeys = reuseRoutes.length > 0 ? reuseRoutes.map((p) => `"${p.name}"`).join(" | ") : "never";
+		return `${header}
+
+declare module '@ubean/scan' {
+  /**
+   * Route layout keys scanned from \`src/layouts/\`.
+   */
+  export type RouteLayoutKey = ${scan.layouts.length > 0 ? scan.layouts.map((l) => `"${l.name}"`).join(" | ") : "never"};
+
+  /**
+   * Map of route name → route path, scanned from \`src/pages/\`.
+   */
+  export interface RoutePathMap {
+${pathMapEntries}
+  }
+
+  /**
+   * Route names (keys of {@link RoutePathMap}).
+   */
+  export type RouteKey = keyof RoutePathMap;
+
+  /**
+   * Route paths (values of {@link RoutePathMap}).
+   */
+  export type RoutePath = RoutePathMap[RouteKey];
+
+  /**
+   * Reuse route keys (pages using \`.reuse.ts\` / \`.reuse.js\` metadata files).
+   */
+  export type ReuseRouteKey = ${reuseKeys};
+
+  /**
+   * Builtin route keys (framework-provided, e.g. \`root\` / \`not_found\`).
+   * Currently unused — reserved for future builtin pages.
+   */
+  export type BuiltinRouteKey = never;
+
+  /**
+   * Route keys that have a corresponding source file (\`.vue\` / \`.md\`).
+   * Excludes reuse routes and builtin routes.
+   *
+   * Use this to index the \`views\` map for component lookup.
+   */
+  export type RouteFileKey = Exclude<RouteKey, ReuseRouteKey | BuiltinRouteKey>;
+}
+
+declare module 'vue-router/auto-routes' {
+  import type { RouteRecordInfo, ParamValue, ParamValueZeroOrOne } from 'vue-router';
+
+  /**
+   * Route named map — enables typed \`useRoute<Name>(name)\` via vue-router's
+   * \`TypesConfig\` augmentation below.
+   *
+   * Each entry describes a route's name, path, and the types of its path
+   * params (raw input vs. resolved value). For routes without params,
+   * \`Record<never, never>\` is used.
+   *
+   * @see https://router.vuejs.org/api/interfaces/RouteRecordInfo.html
+   */
+  export interface RouteNamedMap {
+${scan.pages.length > 0 ? scan.pages.map((p) => `    "${p.name}": ${this.renderRouteRecordInfo(p)};`).join("\n") : "    // (no pages scanned)"}
+  }
+}
+
+declare module 'vue-router' {
+  export interface TypesConfig {
+    RouteNamedMap: import('vue-router/auto-routes').RouteNamedMap;
+  }
+}
+
+export type { RouteLayoutKey, RoutePathMap, RouteKey, RoutePath, ReuseRouteKey, BuiltinRouteKey, RouteFileKey } from '@ubean/scan';
+`;
+	}
+	/**
+	* 渲染单条路由的 `RouteRecordInfo<Name, Path, ParamsRaw, Params>`。
+	*
+	* 参数类型映射:
+	* - 必需参数(`/users/:id`)    → `{ id: ParamValue<true> }` / `{ id: ParamValue<false> }`
+	* - 可选参数(`/users/:id?`)   → `{ id?: ParamValueZeroOrOne<true> }` / `{ id?: ParamValueZeroOrOne<false> }`
+	* - 无参数(`/about`)          → `Record<never, never>`
+	*
+	* `ParamValue<true>` 表示原始输入类型(必需为 string),`ParamValue<false>` 表示
+	* 解析后类型(已编码/解码,可能为 `string | undefined`)。这是 vue-router 的约定。
+	*/
+	renderRouteRecordInfo(page) {
+		const params = extractRouteParams(page.route);
+		const paramsRaw = renderParamsType(params, true);
+		const paramsResolved = renderParamsType(params, false);
+		return `RouteRecordInfo<${JSON.stringify(page.name)}, ${JSON.stringify(page.route)}, ${paramsRaw}, ${paramsResolved}>`;
+	}
+};
+/**
+* Extensions stripped when computing the default import specifier.
+*
+* `.vue` / `.md` / `.mdx` are KEPT — Vite dispatches them to dedicated
+* transforms (vue-loader / markdown) based on the extension, so the
+* explicit suffix is required for correct resolution at runtime.
+*
+* `.ts` / `.tsx` / `.js` / `.jsx` are STRIPPED — TypeScript/Vite convention
+* is to import script modules without their extension.
+*/
+const STRIPPABLE_IMPORT_EXT = /\.(tsx?|jsx?)$/;
+/**
+* Compute the default import specifier for a page.
+*
+* Uses `srcDir` (not `cwd`) as the relative base so that the resulting
+* `@/<rel>` path matches the common `@/` → `src/` path alias. For example,
+* a page at `<cwd>/src/pages/about.vue` becomes `@/pages/about.vue`
+* (NOT `@/src/pages/about.vue`, which would double the `src/` prefix and
+* fail to resolve under the standard alias).
+*/
+function defaultPageImportPath(page, srcDir) {
+	return `@/${relativePosix(srcDir, page.fullPath).replace(STRIPPABLE_IMPORT_EXT, "")}`;
+}
+function defaultLayoutImportPath(layout, srcDir) {
+	return `@/${relativePosix(srcDir, layout.fullPath).replace(STRIPPABLE_IMPORT_EXT, "")}`;
+}
+/**
+* 从 vue-router 风格路径中提取参数信息。
+*
+* 支持的语法:
+* - `:name`     — 必需参数(如 `/users/:id`)
+* - `:name?`    — 可选参数(如 `/users/:id?`)
+* - `:name*`    — 重复参数(零或多个,如 `/files/:path*`)— 当前当作可选处理
+* - `:name+`    — 重复参数(一个或多个,如 `/files/:path+`)— 当前当作必需处理
+* - `:name(...)` — 带自定义正则的参数(如 `:id(\\d+)`)— 提取 `name`,忽略正则
+*
+* 不识别 `:pathMatch(.*)*`(catch-all),由 vue-router 内部处理,在
+* `RouteRecordInfo` 中视为无参数(`Record<never, never>`)。
+*
+* @returns 参数数组,顺序与 path 中出现顺序一致
+*/
+function extractRouteParams(path) {
+	const params = [];
+	const paramRegex = /:([A-Za-z_][A-Za-z0-9_]*)(?:\([^)]*\))?([?*+]?)/g;
+	let match;
+	while ((match = paramRegex.exec(path)) !== null) {
+		const name = match[1];
+		const modifier = match[2];
+		const optional = modifier === "?" || modifier === "*";
+		if (!params.some((p) => p.name === name)) params.push({
+			name,
+			optional
+		});
+	}
+	return params;
+}
+/**
+* 渲染参数类型字面量,用于 `RouteRecordInfo` 的 `ParamsRaw` / `Params` 类型参数位置。
+*
+* @param params   `extractRouteParams` 返回的参数数组
+* @param isRaw    `true` 渲染原始输入类型(`ParamValue<true>` / `ParamValueZeroOrOne<true>`),
+*                 `false` 渲染解析后类型(`ParamValue<false>` / `ParamValueZeroOrOne<false>`)
+* @returns 类型字面量字符串,如 `{ id: ParamValue<true> }` 或 `Record<never, never>`
+*/
+function renderParamsType(params, isRaw) {
+	if (params.length === 0) return "Record<never, never>";
+	return `{\n${params.map((p) => {
+		const optionalMarker = p.optional ? "?" : "";
+		const type = p.optional ? `ParamValueZeroOrOne<${isRaw ? "true" : "false"}>` : `ParamValue<${isRaw ? "true" : "false"}>`;
+		return `    ${p.name}${optionalMarker}: ${type}`;
+	}).join(",\n")}\n  }`;
+}
+function joinPosix(...parts) {
+	return parts.map((p) => p.replace(/\\/g, "/")).join("/").replace(/\/+/g, "/");
+}
+/**
+* 将 `cwd` 与 `target` 合并为最终写入路径。
+*
+* 与 `joinPosix` 不同,此函数会识别 `target` 是否为绝对路径:
+* - 如果 `target` 以 `/` 开头(POSIX 绝对路径)或盘符开头(Windows,如 `C:`),
+*   直接使用 `target`,忽略 `cwd`
+* - 否则,使用 `joinPosix(cwd, target)` 拼接
+*
+* 这是为了支持消费方传入 `path.resolve()` 计算出的绝对路径,
+* 避免出现 `<cwd>/<absolute-target>` 这种重复前缀的错误路径(参见
+* builder `maybeGenerateRouteFiles` 中 `resolve(config.rootDir, ...)` 的调用)。
+*/
+function resolvePath(cwd, target) {
+	const normalized = target.replace(/\\/g, "/");
+	if (normalized.startsWith("/") || /^[a-zA-Z]:[\\/]/.test(normalized)) return normalized;
+	return joinPosix(cwd, normalized);
+}
+function relativePosix(from, to) {
+	const fromParts = resolvePosix(from).split("/").filter(Boolean);
+	const toParts = resolvePosix(to).split("/").filter(Boolean);
+	let i = 0;
+	while (i < fromParts.length && i < toParts.length && fromParts[i] === toParts[i]) i++;
+	const up = fromParts.slice(i).map(() => "..");
+	const down = toParts.slice(i);
+	return [...up, ...down].join("/") || ".";
+}
+function resolvePosix(p) {
+	if (p.startsWith("/")) return p.replace(/\\/g, "/");
+	return p.replace(/\\/g, "/");
+}
+async function writeFile(path, content) {
+	const { mkdir, writeFile: fsWriteFile } = await import("node:fs/promises");
+	const { dirname } = await import("node:path");
+	await mkdir(dirname(path), { recursive: true });
+	await fsWriteFile(path, content, "utf-8");
+}
+//#endregion
+export { DEFAULT_HEADER_COMMENT, RouteFileGenerator, generateRouteFiles };