vitarx-router 4.0.2 → 4.0.4

package/dist/file-router/macros/astValueExtractor.d.ts

@@ -6,10 +6,22 @@
  */
 import type * as BabelTypes from '@babel/types';
 import type { PageOptions } from '../types/index.js';
+/**
+ * 不支持节点的警告信息
+ */
+export interface UnsupportedNodeWarning {
+    /** 不支持的 AST 节点类型 */
+    nodeType: string;
+    /** 属性访问路径，如 "meta.nav.items[0].label" */
+    path: string;
+    /** 修复建议 */
+    suggestion: string;
+}
 /**
  * 从对象表达式提取页面配置
  *
  * @param node - 对象表达式节点
- * @returns 页面配置
+ * @param warnings - 警告收集器（可选，不传则不收集警告）
+ * @returns 页面配置和警告列表
  */
-export declare function extractPageOptions(node: BabelTypes.ObjectExpression): PageOptions;
+export declare function extractPageOptions(node: BabelTypes.ObjectExpression, warnings?: UnsupportedNodeWarning[]): PageOptions;

package/dist/file-router/macros/astValueExtractor.js

@@ -1,12 +1,46 @@
+/**
+ * 不支持节点类型到修复建议的映射
+ */
+const UNSUPPORTED_NODE_SUGGESTIONS = {
+    Identifier: '不支持变量引用，请使用字面量值。例如将 { name: myVar } 改为 { name: "value" }',
+    MemberExpression: '不支持属性访问表达式，请使用字面量值。例如将 { api: config.url } 改为 { api: "https://example.com" }',
+    CallExpression: '不支持函数调用，请使用字面量值。例如将 { id: genId() } 改为 { id: "static-id" }',
+    ArrowFunctionExpression: '不支持箭头函数，请使用字面量值。例如将 { handler: () => {} } 改为 { handler: "handlerName" }',
+    FunctionExpression: '不支持函数表达式，请使用字面量值。例如将 { handler: function() {} } 改为 { handler: "handlerName" }',
+    NewExpression: '不支持 new 表达式（除 new RegExp 外），请使用字面量值',
+    SpreadElement: '不支持展开运算符，请显式列出所有属性',
+    ConditionalExpression: '不支持三元表达式，请使用字面量值。例如将 { val: cond ? "a" : "b" } 改为 { val: "a" }',
+    BinaryExpression: '不支持二元运算表达式，请使用字面量值。例如将 { val: 1 + 2 } 改为 { val: 3 }',
+    LogicalExpression: '不支持逻辑运算表达式，请使用字面量值。例如将 { val: a || "default" } 改为 { val: "default" }',
+    SequenceExpression: '不支持逗号表达式，请使用字面量值',
+    AssignmentExpression: '不支持赋值表达式，请使用字面量值',
+    UpdateExpression: '不支持更新表达式，请使用字面量值。例如将 { val: i++ } 改为 { val: 1 }',
+    TaggedTemplateExpression: '不支持标签模板字符串，请使用普通字符串字面量',
+    ClassExpression: '不支持类表达式，请使用字面量值',
+    ObjectMethod: '不支持对象方法定义，请使用字面量值。例如将 { fn() {} } 改为 { fn: "methodName" }'
+};
+/**
+ * 获取不支持节点的修复建议
+ *
+ * @param nodeType - AST 节点类型
+ * @returns 修复建议
+ */
+function getSuggestion(nodeType) {
+    return (UNSUPPORTED_NODE_SUGGESTIONS[nodeType] ??
+        `不支持 ${nodeType} 类型的表达式，definePage 配置仅支持静态字面量值（字符串、数字、布尔、null、对象、数组、正则、一元表达式、简单模板字符串）`);
+}
 /**
  * 提取字面量值
  *
  * 从 AST 节点提取 JavaScript 字面量值。
+ * 遇到不支持的节点类型时，将警告信息收集到 warnings 数组中。
  *
  * @param node - AST 节点
+ * @param currentPath - 当前属性访问路径
+ * @param warnings - 警告收集器
  * @returns 提取的值
  */
-function extractAstLiteralValue(node) {
+function extractAstLiteralValue(node, currentPath, warnings) {
     switch (node.type) {
         case 'StringLiteral':
             return node.value;
@@ -16,11 +50,57 @@ function extractAstLiteralValue(node) {
             return node.value;
         case 'NullLiteral':
             return null;
+        case 'RegExpLiteral':
+            return new RegExp(node.pattern, node.flags || '');
+        case 'TemplateLiteral': {
+            // 仅支持无表达式的简单模板字符串，如 `hello`
+            if (node.quasis.length === 1 && node.expressions.length === 0) {
+                return node.quasis[0].value.cooked;
+            }
+            warnings.push({
+                nodeType: node.type,
+                path: currentPath,
+                suggestion: '不支持带插值表达式的模板字符串，请使用纯字符串字面量。例如将 `Hello ${name}` 改为 "Hello World"'
+            });
+            return undefined;
+        }
+        case 'UnaryExpression': {
+            const arg = extractAstLiteralValue(node.argument, currentPath, warnings);
+            if (arg === undefined || arg === null)
+                return undefined;
+            switch (node.operator) {
+                case '-':
+                    return -arg;
+                case '+':
+                    return +arg;
+                case '!':
+                    return !arg;
+                case '~':
+                    return ~arg;
+                case 'void':
+                    return undefined;
+                default:
+                    warnings.push({
+                        nodeType: node.type,
+                        path: currentPath,
+                        suggestion: `不支持 "${node.operator}" 一元运算符，仅支持 -, +, !, ~, void`
+                    });
+                    return undefined;
+            }
+        }
         case 'ArrayExpression':
-            return node.elements.map(elem => (elem ? extractAstLiteralValue(elem) : null));
+            return node.elements.map((elem, index) => elem ? extractAstLiteralValue(elem, `${currentPath}[${index}]`, warnings) : null);
         case 'ObjectExpression': {
             const obj = {};
             for (const prop of node.properties) {
+                if (prop.type === 'ObjectMethod') {
+                    warnings.push({
+                        nodeType: 'ObjectMethod',
+                        path: currentPath,
+                        suggestion: getSuggestion('ObjectMethod')
+                    });
+                    continue;
+                }
                 if (prop.type !== 'ObjectProperty')
                     continue;
                 const key = prop.key.type === 'Identifier'
@@ -29,13 +109,19 @@ function extractAstLiteralValue(node) {
                         ? prop.key.value
                         : null;
                 if (key) {
-                    obj[key] = extractAstLiteralValue(prop.value);
+                    obj[key] = extractAstLiteralValue(prop.value, `${currentPath}.${key}`, warnings);
                 }
             }
             return obj;
         }
-        default:
+        default: {
+            warnings.push({
+                nodeType: node.type,
+                path: currentPath,
+                suggestion: getSuggestion(node.type)
+            });
             return undefined;
+        }
     }
 }
 /**
@@ -68,9 +154,11 @@ function extractStringRecord(node) {
  * 提取 meta 值
  *
  * @param node - AST 节点
+ * @param currentPath - 当前属性访问路径
+ * @param warnings - 警告收集器
  * @returns meta 对象
  */
-function extractMetaValue(node) {
+function extractMetaValue(node, currentPath, warnings) {
     if (node.type !== 'ObjectExpression')
         return undefined;
     const meta = {};
@@ -84,7 +172,7 @@ function extractMetaValue(node) {
                 : null;
         if (!key)
             continue;
-        meta[key] = extractAstLiteralValue(prop.value);
+        meta[key] = extractAstLiteralValue(prop.value, `${currentPath}.${key}`, warnings);
     }
     return meta;
 }
@@ -222,10 +310,12 @@ function extractAliasValue(node) {
  * 从对象表达式提取页面配置
  *
  * @param node - 对象表达式节点
- * @returns 页面配置
+ * @param warnings - 警告收集器（可选，不传则不收集警告）
+ * @returns 页面配置和警告列表
  */
-export function extractPageOptions(node) {
+export function extractPageOptions(node, warnings) {
     const options = {};
+    const warnList = warnings ?? [];
     for (const prop of node.properties) {
         if (prop.type !== 'ObjectProperty')
             continue;
@@ -243,7 +333,7 @@ export function extractPageOptions(node) {
                 }
                 break;
             case 'meta':
-                options.meta = extractMetaValue(prop.value);
+                options.meta = extractMetaValue(prop.value, 'meta', warnList);
                 break;
             case 'pattern':
                 options.pattern = extractPatternValue(prop.value);

package/dist/file-router/macros/definePage.js

@@ -56,6 +56,7 @@ export function parseDefinePage(content, filePath) {
     try {
         const ast = parseCode(content);
         const routeOptionsList = [];
+        const warnings = [];
         babelTraverse(ast, {
             CallExpression(nodePath) {
                 const { node } = nodePath;
@@ -66,7 +67,7 @@ export function parseDefinePage(content, filePath) {
                 if (!arg || arg.type !== 'ObjectExpression') {
                     return;
                 }
-                const options = extractPageOptions(arg);
+                const options = extractPageOptions(arg, warnings);
                 routeOptionsList.push(options);
             }
         });
@@ -76,6 +77,10 @@ export function parseDefinePage(content, filePath) {
         if (routeOptionsList.length > 1) {
             warn('检测到多个 definePage 调用，将合并所有配置，建议每个文件只调用一次 definePage', `in ${filePath}`);
         }
+        // 输出不支持节点的警告
+        for (const w of warnings) {
+            warn(`definePage 配置解析警告: 路径 "${w.path}" 处遇到不支持的 ${w.nodeType} 节点，该属性值将被忽略。${w.suggestion}`, `in ${filePath}`);
+        }
         return mergePageOptions(...routeOptionsList);
     }
     catch (e) {

package/dist/file-router/manager/file-processor.d.ts

@@ -9,7 +9,7 @@
  */
 import { type PageDirConfig, type ResolvedConfig } from '../config/index.js';
 import { type FileInfo } from '../parser/parsePage.js';
-import type { PageOptions, PageParseResult, ScanNode } from '../types/index.js';
+import type { PageParseResult, ScanNode } from '../types/index.js';
 /**
  * 扫描阶段的目录配置
  *
@@ -97,24 +97,4 @@ export interface ProcessPageFileParams {
  * @returns 新创建的路由节点；合并到已有路由时返回 null
  */
 export declare function processPageFile(params: ProcessPageFileParams, context: ProcessorContext): ScanNode | null;
-/**
- * 解析分组目录的自定义路径和选项
- *
- * 通过 groupParser 解析目录名，支持两种返回格式：
- * 1. 字符串：仅自定义路径
- * 2. 对象：自定义路径 + 路由选项（如 meta、name 等）
- *
- * 未配置 groupParser 时，直接使用原始目录名作为路径。
- *
- * @param fileName - 目录名
- * @param filePath - 目录完整路径
- * @param groupParser - 分组解析器，可选
- * @returns 解析后的路径和选项
- */
-export declare function parseGroupResult(fileName: string, filePath: string, groupParser?: (dirName: string, dirPath: string) => string | {
-    path: string;
-    options?: PageOptions;
-}): {
-    routePath: string;
-    options?: PageOptions;
-};
+export { parseGroupResult } from '../utils/groupParser.js';

package/dist/file-router/manager/file-processor.js

@@ -104,27 +104,5 @@ export function processPageFile(params, context) {
     pageMapping.set(parsed.path, route);
     return route;
 }
-/**
- * 解析分组目录的自定义路径和选项
- *
- * 通过 groupParser 解析目录名，支持两种返回格式：
- * 1. 字符串：仅自定义路径
- * 2. 对象：自定义路径 + 路由选项（如 meta、name 等）
- *
- * 未配置 groupParser 时，直接使用原始目录名作为路径。
- *
- * @param fileName - 目录名
- * @param filePath - 目录完整路径
- * @param groupParser - 分组解析器，可选
- * @returns 解析后的路径和选项
- */
-export function parseGroupResult(fileName, filePath, groupParser) {
-    if (!groupParser) {
-        return { routePath: fileName };
-    }
-    const result = groupParser(fileName, filePath);
-    if (typeof result === 'string') {
-        return { routePath: result };
-    }
-    return { routePath: result.path, options: result.options };
-}
+// parseGroupResult 已移至 utils/groupParser.ts，此处重新导出以保持向后兼容
+export { parseGroupResult } from '../utils/groupParser.js';

package/dist/file-router/manager/index.js

@@ -122,6 +122,7 @@ export class FileRouter {
             fileMap: this.fileMap,
             pages: this.config.pages,
             pageParser: this.config.pageParser,
+            groupParser: this.config.groupParser,
             pathStrategy: this.config.pathStrategy
         });
     }

package/dist/file-router/parser/routePath.d.ts

@@ -1,10 +1,11 @@
 import { type PageDirConfig } from '../config/resolve.js';
-import type { PageParser, PathStrategy, ScanNode } from '../types/index.js';
+import type { GroupParser, PageParser, PathStrategy, ScanNode } from '../types/index.js';
 import { type FileInfo } from './parsePage.js';
 interface RouteFullPathContext {
     fileMap: Map<string, ScanNode>;
     pages: readonly PageDirConfig[];
     pageParser?: PageParser;
+    groupParser?: GroupParser;
     pathStrategy: PathStrategy;
 }
 /**

package/dist/file-router/parser/routePath.js

@@ -5,6 +5,7 @@
  * 支持已跟踪（在路由树中）和未跟踪（尚未扫描）两种场景。
  */
 import nodePath from 'node:path';
+import { parseGroupResult } from '../utils/groupParser.js';
 import { applyPathStrategy } from '../utils/pathStrategy.js';
 import { normalizeRoutePath, resolvePathVariable } from '../utils/pathUtils.js';
 import { isPageFileInDirs } from './filterUtils.js';
@@ -48,27 +49,39 @@ function computeNodeFullPath(node) {
  * @returns 完整路由路径，非页面文件返回 null
  */
 export function computeRouteFullPath(filePath, fileInfo, context) {
-    const { fileMap, pages, pageParser, pathStrategy } = context;
+    const { fileMap, pages, pageParser, groupParser, pathStrategy } = context;
+    // 场景一：文件已在路由树中，直接沿 parent 链计算 fullPath
     const node = fileMap.get(filePath);
     if (node) {
         return computeNodeFullPath(node);
     }
+    // 场景二：文件尚未被扫描跟踪，需要从文件路径手动计算
     const page = isPageFileInDirs(filePath, pages);
     if (!page)
         return null;
+    // 解析文件名得到路径段（index 文件不产生路径段）
     const parsed = parsePageFile(filePath, pageParser, fileInfo);
-    const pathSegment = parsed.path === 'index' ? '' : applyFullPathStrategy(parsed.path, pathStrategy);
+    const pathSegment = parsed.path === 'index' ? '' : parsed.path;
     const segments = pathSegment ? [pathSegment] : [];
+    // 从文件所在目录向上遍历至 pages.dir 根目录，逐级收集路径段
     let dirPath = nodePath.dirname(filePath);
     while (dirPath.length > page.dir.length) {
         const dirNode = fileMap.get(dirPath);
         if (dirNode) {
+            // 目录已在路由树中，直接复用其 fullPath 作为前缀，无需继续向上遍历
             const parentFullPath = computeNodeFullPath(dirNode);
-            return normalizeRoutePath(parentFullPath + '/' + segments.join('/'));
+            segments.unshift(parentFullPath);
+            return normalizeRoutePath(applyFullPathStrategy(segments.join('/'), pathStrategy));
         }
-        segments.unshift(applyFullPathStrategy(nodePath.basename(dirPath), pathStrategy));
+        // 目录未被跟踪，通过 groupParser 解析目录名（如 "1.user" → "user"），再作为路径段
+        const dirName = nodePath.basename(dirPath);
+        const { routePath: parsedDirName } = parseGroupResult(dirName, dirPath, groupParser);
+        segments.unshift(parsedDirName);
         dirPath = nodePath.dirname(dirPath);
     }
-    const prefix = page.prefix ? applyFullPathStrategy(page.prefix, pathStrategy) : '';
-    return normalizeRoutePath(prefix + '/' + segments.join('/'));
+    // 顶层路由拼接 prefix
+    if (page.prefix)
+        segments.unshift(page.prefix);
+    // 统一应用路径策略（命名转换 + 动态参数转换）并规范化
+    return normalizeRoutePath(applyFullPathStrategy(segments.join('/'), pathStrategy));
 }

package/dist/file-router/utils/groupParser.d.ts

@@ -0,0 +1,28 @@
+/**
+ * @fileoverview 分组目录解析工具
+ *
+ * 提供 groupParser 的调用封装，将目录名解析为路由路径和选项。
+ * 供扫描器和路径计算等模块共同使用。
+ */
+import type { PageOptions } from '../types/index.js';
+/**
+ * 解析分组目录的自定义路径和选项
+ *
+ * 通过 groupParser 解析目录名，支持两种返回格式：
+ * 1. 字符串：仅自定义路径
+ * 2. 对象：自定义路径 + 路由选项（如 meta、name 等）
+ *
+ * 未配置 groupParser 时，直接使用原始目录名作为路径。
+ *
+ * @param fileName - 目录名
+ * @param filePath - 目录完整路径
+ * @param groupParser - 分组解析器，可选
+ * @returns 解析后的路径和选项
+ */
+export declare function parseGroupResult(fileName: string, filePath: string, groupParser?: (dirName: string, dirPath: string) => string | {
+    path: string;
+    options?: PageOptions;
+}): {
+    routePath: string;
+    options?: PageOptions;
+};

package/dist/file-router/utils/groupParser.js

@@ -0,0 +1,24 @@
+/**
+ * 解析分组目录的自定义路径和选项
+ *
+ * 通过 groupParser 解析目录名，支持两种返回格式：
+ * 1. 字符串：仅自定义路径
+ * 2. 对象：自定义路径 + 路由选项（如 meta、name 等）
+ *
+ * 未配置 groupParser 时，直接使用原始目录名作为路径。
+ *
+ * @param fileName - 目录名
+ * @param filePath - 目录完整路径
+ * @param groupParser - 分组解析器，可选
+ * @returns 解析后的路径和选项
+ */
+export function parseGroupResult(fileName, filePath, groupParser) {
+    if (!groupParser) {
+        return { routePath: fileName };
+    }
+    const result = groupParser(fileName, filePath);
+    if (typeof result === 'string') {
+        return { routePath: result };
+    }
+    return { routePath: result.path, options: result.options };
+}

package/dist/file-router/utils/index.d.ts

@@ -10,3 +10,4 @@ export * from './pathStrategy.js';
 export * from '../config/validate.js';
 export * from './fileReader.js';
 export * from './findRoute.js';
+export * from './groupParser.js';

package/dist/file-router/utils/index.js

@@ -10,3 +10,4 @@ export * from './pathStrategy.js';
 export * from '../config/validate.js';
 export * from './fileReader.js';
 export * from './findRoute.js';
+export * from './groupParser.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vitarx-router",
-  "version": "4.0.2",
+  "version": "4.0.4",
   "description": "Official routing solution for Vitarx framework with declarative routing, navigation guards, dynamic routes, file-based routing with HMR, and full TypeScript support.",
   "author": "ZhuChonglin <8210856@qq.com>",
   "license": "MIT",