@leejung/hvigor-nav-router-plugin 1.0.0

package/README.md

@@ -0,0 +1,259 @@
+# @leejung/hvigor-nav-router-plugin
+
+`@leejung/nav-router` 的 hvigor 构建插件。
+
+它负责在构建阶段自动扫描页面和弹窗入口，生成 `route_map.json`，并把模块的 `module.json5` 自动补齐 `routerMap` 配置，避免继续手工维护路由表。
+
+## 解决的问题
+
+从 `HMRouter` 迁移到 `Navigation + route_map.json` 后，项目会多出两类重复劳动：
+
+1. 每个模块都要维护自己的 `src/main/resources/base/profile/route_map.json`
+2. 每个模块都要在 `module.json5` 里补 `routerMap: "$profile:route_map"`
+
+这个插件把这两件事放进 hvigor 构建流程里自动完成。
+
+## 当前仓库的推荐约定
+
+当前仓库的主约定是：
+
+1. 路由名统一定义在 `features/appcommon/src/main/ets/constants/PageConstants.ets`
+2. 页面文件只保留 `@Builder export function XxxBuilder()`
+3. 不再在页面文件里额外维护路由装饰器或独立常量
+
+示例：
+
+```typescript
+// features/appcommon/src/main/ets/constants/PageConstants.ets
+export class PageConstants {
+  public static readonly Home = 'page://HomePage'
+  public static readonly StopServerNoticeDialog = 'dialog://StopServerNoticeDialog'
+}
+```
+
+```typescript
+// features/home/src/main/ets/pages/HomePage.ets
+@Builder
+export function HomePageBuilder() {
+  HomePage()
+}
+```
+
+插件会优先按 `Builder` 名去中央 `PageConstants` 中查找路由名。
+
+## 插件做了什么
+
+每次构建时，插件会：
+
+1. 扫描模块下的 `src/main/ets/pages` 和 `src/main/ets/dialogs`
+2. 找出带 `@Builder export function XxxBuilder()` 的 `.ets` 文件
+3. 解析对应路由名
+4. 生成或更新 `src/main/resources/base/profile/route_map.json`
+5. 向 `module.json5` 注入 `"routerMap": "$profile:route_map"`
+
+## 路由名解析优先级
+
+主路径是中央 `PageConstants`，但为了兼容迁移过程，扫描器还保留了兜底能力。
+
+优先级从高到低：
+
+1. `@NavRoute({ url: ... })` 装饰器
+2. `// @NavRoute({ url: '...' })` 注释
+3. `export const NAV_ROUTE_NAME = ...`
+4. 中央 `PageConstants` 映射
+5. 按目录和文件名兜底推导
+
+文件名兜底规则：
+
+- `src/main/ets/pages/HomePage.ets` -> `page://HomePage`
+- `src/main/ets/dialogs/StopServerNotice.ets` -> `dialog://StopServerNotice`
+
+## 目录要求
+
+默认扫描目录：
+
+```text
+src/main/ets/pages
+src/main/ets/dialogs
+```
+
+默认输出文件：
+
+```text
+src/main/resources/base/profile/route_map.json
+```
+
+页面文件必须满足这个条件才会被识别成路由入口：
+
+```typescript
+@Builder
+export function XxxBuilder() {
+  XxxPage()
+}
+```
+
+如果没有 `@Builder export function XxxBuilder()`，插件会直接跳过该文件。
+
+## 在项目里的接入方式
+
+当前仓库不是通过 npm 包名引用，而是直接在 `hvigorfile.ts` 中引用本地源码：
+
+HAP 模块：
+
+```typescript
+import { hapTasks } from '@ohos/hvigor-ohos-plugin';
+import { navRouterHapPlugin } from '../libs/hvigor-nav-router-plugin/src/index';
+
+export default {
+  system: hapTasks,
+  plugins: [navRouterHapPlugin()]
+}
+```
+
+HAR 模块：
+
+```typescript
+import { harTasks } from '@ohos/hvigor-ohos-plugin';
+import { navRouterHarPlugin } from '../../libs/hvigor-nav-router-plugin/src/index';
+
+export default {
+  system: harTasks,
+  plugins: [navRouterHarPlugin()]
+}
+```
+
+当前仓库里的接入点包括：
+
+- `entry/hvigorfile.ts`
+- `features/appcommon/hvigorfile.ts`
+- `features/home/hvigorfile.ts`
+- `features/login/hvigorfile.ts`
+- `features/search/hvigorfile.ts`
+- `features/cartype/hvigorfile.ts`
+- `features/trip/hvigorfile.ts`
+- `features/mine/hvigorfile.ts`
+
+## 插件 API
+
+### `navRouterHapPlugin(config?)`
+
+给 HAP 模块使用。
+
+### `navRouterHarPlugin(config?)`
+
+给 HAR 模块使用。
+
+### `PluginConfig`
+
+```typescript
+interface PluginConfig {
+  scanDirs?: string[]
+  routeMapPath?: string
+}
+```
+
+字段说明：
+
+- `scanDirs`: 自定义扫描目录，默认是 `pages + dialogs`
+- `routeMapPath`: 自定义输出文件路径，默认是 `src/main/resources/base/profile/route_map.json`
+
+示例：
+
+```typescript
+navRouterHarPlugin({
+  scanDirs: [
+    'src/main/ets/pages',
+    'src/main/ets/dialogs',
+    'src/main/ets/sheets'
+  ],
+  routeMapPath: 'src/main/resources/base/profile/route_map.json'
+})
+```
+
+## 生成结果示例
+
+```json
+{
+  "routerMap": [
+    {
+      "name": "dialog://StopServerNoticeDialog",
+      "pageSourceFile": "src/main/ets/dialogs/StopServerNotice.ets",
+      "buildFunction": "StopServerNoticeDialogBuilder"
+    },
+    {
+      "name": "page://HomePage",
+      "pageSourceFile": "src/main/ets/pages/HomePage.ets",
+      "buildFunction": "HomePageBuilder"
+    }
+  ]
+}
+```
+
+同时模块的 `module.json5` 会被补成：
+
+```json5
+{
+  "module": {
+    "name": "home",
+    "type": "har",
+    "routerMap": "$profile:route_map"
+  }
+}
+```
+
+## 与 HMRouter 插件的区别
+
+| 项目 | HMRouter 插件 | 本插件 |
+|---|---|---|
+| 路由来源 | 运行时黑盒注册 | 构建期静态生成 |
+| 路由表 | 框架内部维护 | `route_map.json` 可直接查看 |
+| 调试方式 | 主要靠运行时排查 | 可直接核对生成产物 |
+| 项目规范 | 常见是页面内分散声明 | 推荐中央 `PageConstants` |
+
+## 调试与排障
+
+### 1. 页面没进 `route_map.json`
+
+优先检查：
+
+1. 文件是否在 `pages/` 或 `dialogs/` 目录下
+2. 是否存在顶层 `@Builder export function XxxBuilder()`
+3. `PageConstants` 是否有对应路由常量
+4. Builder 名和路由名是否能一一对应
+
+### 2. 改了插件源码但构建还在跑旧逻辑
+
+`src/index.ts` 已经在每次取插件实例前主动清理：
+
+- `./plugin`
+- `./scanner`
+- `./ast-utils`
+
+对应的 `require.cache`。
+
+这样 hvigor daemon 即使复用进程，也会重新加载磁盘上的插件源码。
+
+### 3. 改了 `PageConstants` 但生成结果没更新
+
+扫描器在每次 `scanRouteAnnotations(moduleDir)` 开头都会清理该模块的中央路由缓存，避免 daemon 增量构建拿到过期映射。
+
+### 4. 想强制确认产物
+
+直接检查各模块生成的：
+
+```text
+src/main/resources/base/profile/route_map.json
+```
+
+## 最小接入清单
+
+给一个新模块接入时，只要做这几步：
+
+1. 在模块 `hvigorfile.ts` 注册插件
+2. 在 `PageConstants` 里补路由常量
+3. 在页面文件里提供 `@Builder export function XxxBuilder()`
+4. 构建一次，确认生成了 `route_map.json`
+
+## 相关文档
+
+- [nav-router README](../nav-router/README.md)

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@leejung/hvigor-nav-router-plugin",
+  "version": "1.0.0",
+  "description": "Hvigor build plugin for @leejung/nav-router - auto-generates route_map.json from @NavRoute annotations",
+  "main": "src/index.ts",
+  "keywords": [
+    "harmonyos",
+    "hvigor",
+    "router",
+    "navigation",
+    "plugin",
+    "nav-router"
+  ],
+  "author": "leejung",
+  "license": "Apache-2.0",
+  "dependencies": {
+    "ts-morph": "^23.0.0"
+  },
+  "peerDependencies": {
+    "@ohos/hvigor": ">=4.0.0",
+    "@ohos/hvigor-ohos-plugin": ">=4.0.0"
+  }
+}

package/src/ast-utils.ts

@@ -0,0 +1,313 @@
+/**
+ * @leejung/hvigor-nav-router-plugin — AST 工具
+ *
+ * 基于 ts-morph 提供常量解析、import 追踪等能力。
+ * 参考 @hadss/hmrouter-plugin 的 TsAstUtil 实现。
+ */
+
+import { Project, SourceFile, SyntaxKind, Node } from 'ts-morph';
+import * as path from 'path';
+import * as fs from 'fs';
+
+/** 全局共享的 ts-morph Project 实例（避免重复创建） */
+let sharedProject: Project | undefined;
+
+/** 获取或创建共享的 ts-morph Project */
+export function getProject(): Project {
+  if (!sharedProject) {
+    sharedProject = new Project({
+      compilerOptions: {
+        allowJs: true,
+        noEmit: true,
+        experimentalDecorators: true,
+      },
+      skipAddingFilesFromTsConfig: true,
+      skipFileDependencyResolution: true,
+    });
+  }
+  return sharedProject;
+}
+
+/** 重置共享 Project（构建完成后清理） */
+export function resetProject(): void {
+  sharedProject = undefined;
+}
+
+/** 将路径分隔符统一为正斜杠 */
+export function normalizeSlashes(filePath: string): string {
+  return filePath.replace(/\\/g, '/');
+}
+
+/**
+ * import 映射表条目
+ * key: 导入的名称（如 'PageConstants'）
+ * value: { moduleSpecifier, isDefault }
+ */
+export interface ImportEntry {
+  moduleSpecifier: string;
+  isDefault: boolean;
+}
+
+/** 构建文件的 import 映射表 */
+export function buildImportMap(sourceFile: SourceFile): Map<string, ImportEntry> {
+  const importMap = new Map<string, ImportEntry>();
+  const importDecls = sourceFile.getImportDeclarations();
+  for (const decl of importDecls) {
+    const moduleSpecifier = decl.getModuleSpecifierValue();
+    const defaultImport = decl.getDefaultImport();
+    if (defaultImport) {
+      importMap.set(defaultImport.getText(), { moduleSpecifier, isDefault: true });
+    }
+    const namedImports = decl.getNamedImports();
+    for (const named of namedImports) {
+      const name = named.getAliasNode()?.getText() ?? named.getName();
+      importMap.set(name, { moduleSpecifier, isDefault: false });
+    }
+  }
+  return importMap;
+}
+
+/**
+ * 从源文件中解析常量值（字符串字面量）
+ *
+ * 支持两种形式:
+ * 1. 顶级 const: `export const FOO = 'xxx'`
+ * 2. 类的静态属性: `export class Foo { static Bar = 'xxx' }`
+ */
+export function parseConstantValue(
+  sourceFile: SourceFile,
+  variableName: string,
+  propertyName?: string
+): string | undefined {
+  if (propertyName) {
+    // 解析类静态属性: PageConstants.Home
+    const classDecl = sourceFile.getClass(variableName);
+    if (!classDecl) {
+      return undefined;
+    }
+    const prop = classDecl.getStaticProperty(propertyName);
+    if (!prop || !Node.isPropertyDeclaration(prop)) {
+      return undefined;
+    }
+    const initializer = prop.getInitializer();
+    if (!initializer || !Node.isStringLiteral(initializer)) {
+      return undefined;
+    }
+    return initializer.getLiteralValue();
+  }
+  // 解析顶级常量: export const FOO = 'xxx'
+  const varDecl = sourceFile.getVariableDeclaration(variableName);
+  if (!varDecl) {
+    return undefined;
+  }
+  const initializer = varDecl.getInitializer();
+  if (!initializer || !Node.isStringLiteral(initializer)) {
+    return undefined;
+  }
+  return initializer.getLiteralValue();
+}
+
+/** 已解析的常量值缓存: Map<filePath + '::' + key, value> */
+const constantCache = new Map<string, string>();
+
+/** 清除常量缓存 */
+export function clearConstantCache(): void {
+  constantCache.clear();
+}
+
+/**
+ * 解析跨文件常量引用
+ *
+ * @param importEntry 从 importMap 中取得的导入条目
+ * @param variableName 变量名（如 'PageConstants'）
+ * @param propertyName 属性名（如 'Home'），对顶级常量为 undefined
+ * @param currentFileDir 当前文件所在目录
+ * @param moduleDir 当前模块根目录
+ */
+export function resolveConstantAcrossFiles(
+  importEntry: ImportEntry,
+  variableName: string,
+  propertyName: string | undefined,
+  currentFileDir: string,
+  moduleDir: string
+): string | undefined {
+  const cacheKey = `${importEntry.moduleSpecifier}::${variableName}${propertyName ? '.' + propertyName : ''}`;
+  const cached = constantCache.get(cacheKey);
+  if (cached !== undefined) {
+    return cached;
+  }
+
+  const resolvedPath = resolveModuleSpecifier(importEntry.moduleSpecifier, currentFileDir, moduleDir);
+  if (!resolvedPath) {
+    return undefined;
+  }
+
+  const project = getProject();
+  let sf = project.getSourceFile(resolvedPath);
+  if (!sf) {
+    if (!fs.existsSync(resolvedPath)) {
+      return undefined;
+    }
+    sf = project.addSourceFileAtPath(resolvedPath);
+  }
+
+  const value = parseConstantValue(sf, variableName, propertyName);
+  if (value !== undefined) {
+    constantCache.set(cacheKey, value);
+  }
+  return value;
+}
+
+/**
+ * 解析 module specifier 到实际文件路径
+ *
+ * 1. 相对路径 (./xxx, ../xxx) → 直接解析
+ * 2. 模块名 (appcommon, @life/zcommon) → 通过 oh_modules 查找
+ */
+function resolveModuleSpecifier(specifier: string, currentFileDir: string, moduleDir: string): string | undefined {
+  if (specifier.startsWith('.')) {
+    // 相对路径
+    return resolveLocalFile(path.resolve(currentFileDir, specifier));
+  }
+
+  // 模块引用 — 在 oh_modules 中查找
+  // 查找顺序: moduleDir/oh_modules → 逐级向上
+  const ohModulePaths = [
+    path.join(moduleDir, 'oh_modules', specifier),
+  ];
+
+  for (const ohModulePath of ohModulePaths) {
+    if (!fs.existsSync(ohModulePath)) {
+      continue;
+    }
+
+    // 尝试读取模块的 Index.ets 或 oh-package.json5 中的 main
+    const indexFile = resolveLocalFile(path.join(ohModulePath, 'Index'));
+    if (indexFile) {
+      return indexFile;
+    }
+
+    // 尝试 src/main/ets 目录下的 Index
+    const srcIndex = resolveLocalFile(path.join(ohModulePath, 'src', 'main', 'ets', 'Index'));
+    if (srcIndex) {
+      return srcIndex;
+    }
+  }
+
+  return undefined;
+}
+
+/** 尝试解析文件路径（支持省略 .ets/.ts 后缀） */
+function resolveLocalFile(basePath: string): string | undefined {
+  const extensions = ['', '.ets', '.ts', '.js'];
+  for (const ext of extensions) {
+    const fullPath = basePath + ext;
+    if (fs.existsSync(fullPath) && fs.statSync(fullPath).isFile()) {
+      return fullPath;
+    }
+  }
+  return undefined;
+}
+
+/**
+ * 从桶导出文件（Index.ets）追踪实际导出源
+ *
+ * 如果 Index.ets 包含 `export { PageConstants } from './constants/PageConstants'`，
+ * 则追踪到 `./constants/PageConstants.ets` 并在其中解析常量。
+ */
+export function resolveReExport(
+  indexFile: SourceFile,
+  exportName: string,
+  indexFileDir: string
+): SourceFile | undefined {
+  const project = getProject();
+  const exportDecls = indexFile.getExportDeclarations();
+  for (const exportDecl of exportDecls) {
+    const specifier = exportDecl.getModuleSpecifierValue();
+    if (!specifier) {
+      continue;
+    }
+    const resolvedPath = resolveLocalFile(path.resolve(indexFileDir, specifier));
+    if (!resolvedPath) {
+      continue;
+    }
+
+    let sf = project.getSourceFile(resolvedPath);
+    if (!sf) {
+      if (!fs.existsSync(resolvedPath)) {
+        continue;
+      }
+      sf = project.addSourceFileAtPath(resolvedPath);
+    }
+
+    const namedExports = exportDecl.getNamedExports();
+    if (namedExports.length === 0) {
+      if (sf.getClass(exportName) || sf.getVariableDeclaration(exportName)) {
+        return sf;
+      }
+      const nestedSource = resolveReExport(sf, exportName, path.dirname(resolvedPath));
+      if (nestedSource) {
+        return nestedSource;
+      }
+      continue;
+    }
+
+    for (const named of namedExports) {
+      const name = named.getAliasNode()?.getText() ?? named.getName();
+      if (name === exportName) {
+        return sf;
+      }
+    }
+  }
+  return undefined;
+}
+
+/**
+ * 完整的跨文件常量解析（含桶导出追踪）
+ */
+export function resolveConstantFull(
+  importEntry: ImportEntry,
+  variableName: string,
+  propertyName: string | undefined,
+  currentFileDir: string,
+  moduleDir: string
+): string | undefined {
+  const cacheKey = `${importEntry.moduleSpecifier}::${variableName}${propertyName ? '.' + propertyName : ''}`;
+  const cached = constantCache.get(cacheKey);
+  if (cached !== undefined) {
+    return cached;
+  }
+
+  const resolvedPath = resolveModuleSpecifier(importEntry.moduleSpecifier, currentFileDir, moduleDir);
+  if (!resolvedPath) {
+    return undefined;
+  }
+
+  const project = getProject();
+  let sf = project.getSourceFile(resolvedPath);
+  if (!sf) {
+    if (!fs.existsSync(resolvedPath)) {
+      return undefined;
+    }
+    sf = project.addSourceFileAtPath(resolvedPath);
+  }
+
+  // 先尝试直接在入口文件解析
+  let value = parseConstantValue(sf, variableName, propertyName);
+  if (value !== undefined) {
+    constantCache.set(cacheKey, value);
+    return value;
+  }
+
+  // 尝试追踪 re-export
+  const reExportSource = resolveReExport(sf, variableName, path.dirname(resolvedPath));
+  if (reExportSource) {
+    value = parseConstantValue(reExportSource, variableName, propertyName);
+    if (value !== undefined) {
+      constantCache.set(cacheKey, value);
+      return value;
+    }
+  }
+
+  return undefined;
+}

package/src/index.ts

@@ -0,0 +1,45 @@
+/**
+ * @leejung/hvigor-nav-router-plugin
+ *
+ * Hvigor 构建插件，为 @leejung/nav-router 自动生成 route_map.json。
+ *
+ * Hvigor worker 可能会复用 require 缓存，导致本地插件源码修改后仍执行旧逻辑。
+ * 这里在每次取插件实例前主动清理本插件模块缓存，确保总是使用磁盘上的最新源码。
+ */
+
+import type { HvigorPlugin } from '@ohos/hvigor';
+import type { PluginConfig, RouteMapEntry, RouteMapFile } from './types';
+
+interface PluginModule {
+  navRouterHapPlugin(config?: PluginConfig): HvigorPlugin;
+  navRouterHarPlugin(config?: PluginConfig): HvigorPlugin;
+}
+
+interface RuntimeRequire {
+  (id: string): unknown;
+  cache?: Record<string, unknown>;
+  resolve(id: string): string;
+}
+
+declare const require: RuntimeRequire;
+
+function loadPluginModule(): PluginModule {
+  const moduleIds = ['./plugin', './scanner', './ast-utils'];
+  for (const moduleId of moduleIds) {
+    const resolved = require.resolve(moduleId);
+    if (require.cache && Object.prototype.hasOwnProperty.call(require.cache, resolved)) {
+      delete require.cache[resolved];
+    }
+  }
+  return require('./plugin') as PluginModule;
+}
+
+export function navRouterHapPlugin(config?: PluginConfig): HvigorPlugin {
+  return loadPluginModule().navRouterHapPlugin(config);
+}
+
+export function navRouterHarPlugin(config?: PluginConfig): HvigorPlugin {
+  return loadPluginModule().navRouterHarPlugin(config);
+}
+
+export type { PluginConfig, RouteMapEntry, RouteMapFile };

package/src/plugin.ts

@@ -0,0 +1,97 @@
+/**
+ * @leejung/hvigor-nav-router-plugin — 核心插件逻辑
+ *
+ * 在 apply() 阶段（PreBuild 之前）完成：
+ *   1. 扫描 @Builder export function 注解，生成 route_map_<module>.json
+ *   2. 自动向 module.json5 注入 routerMap 字段
+ *
+ * 为什么在 apply() 而非 registerTask() 中扫描：
+ *   module.routerMap = "$profile:xxx" 在 PreBuild 阶段会硬校验文件存在性，
+ *   与 HMRouter 使用 metadata.resource（软引用，不校验）不同。
+ *   在 apply() 中完成扫描+写入，PreBuild 时文件已就绪，无需种子文件。
+ *
+ * 为什么每个模块用独立文件名（route_map_<module>.json）：
+ *   HAR 资源合并到 entry HAP 时，同名文件会产生 "defined repeatedly" 警告。
+ *   独立文件名避免跨模块命名冲突。
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import { HvigorNode, HvigorPlugin } from '@ohos/hvigor';
+import { OhosPluginId, OhosHapContext, OhosHarContext } from '@ohos/hvigor-ohos-plugin';
+import { scanRouteAnnotations } from './scanner';
+import { PluginConfig, RouteMapEntry, RouteMapFile } from './types';
+
+/** 生成模块专属的 route_map 文件路径 */
+function getRouteMapPath(moduleDir: string, moduleName: string, config?: PluginConfig): string {
+  if (config?.routeMapPath) {
+    return path.join(moduleDir, config.routeMapPath);
+  }
+  const fileName = `route_map_${moduleName}.json`;
+  return path.join(moduleDir, 'src', 'main', 'resources', 'base', 'profile', fileName);
+}
+
+/** 将路由条目写入 route_map 文件，内容未变化时跳过写入 */
+function writeRouteMap(outputPath: string, entries: RouteMapEntry[]): void {
+  const routeMapFile: RouteMapFile = { routerMap: entries };
+  const nextContent = JSON.stringify(routeMapFile, null, 2) + '\n';
+
+  fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+
+  const currentContent = fs.existsSync(outputPath) ? fs.readFileSync(outputPath, 'utf8') : '';
+  if (currentContent !== nextContent) {
+    fs.writeFileSync(outputPath, nextContent, 'utf8');
+    console.info(`[NavRouterPlugin] 已同步 ${entries.length} 条路由 -> ${outputPath}`);
+  }
+}
+
+/**
+ * 创建 hvigor 插件实例。
+ *
+ * @param ohosPluginId OhosPluginId.OHOS_HAP_PLUGIN 或 OhosPluginId.OHOS_HAR_PLUGIN
+ * @param config 插件配置
+ */
+function createNavRouterPlugin(ohosPluginId: string, config?: PluginConfig): HvigorPlugin {
+  return {
+    pluginId: '@leejung/hvigor-nav-router-plugin',
+
+    apply(node: HvigorNode): void {
+      const context = node.getContext(ohosPluginId) as OhosHapContext | OhosHarContext;
+      if (!context) {
+        console.warn(`[NavRouterPlugin] 无法获取模块上下文 (${ohosPluginId})，跳过 ${node.getNodeName()}`);
+        return;
+      }
+
+      const moduleName = node.getNodeName();
+      const moduleDir = path.resolve(node.getNodePath());
+      const routeMapPath = getRouteMapPath(moduleDir, moduleName, config);
+      const profileRef = `$profile:route_map_${moduleName}`;
+
+      // apply 阶段直接完成扫描+写入（PreBuild 之前）
+      const entries = scanRouteAnnotations(moduleDir, config);
+      writeRouteMap(routeMapPath, entries);
+
+      // 向 module.json5 注入 routerMap 引用（幂等操作）
+      context.targets((_target) => {
+        const moduleJsonOpt = context.getModuleJsonOpt();
+        if (moduleJsonOpt?.module) {
+          if (moduleJsonOpt.module['routerMap'] !== profileRef) {
+            moduleJsonOpt.module['routerMap'] = profileRef;
+            context.setModuleJsonOpt(moduleJsonOpt);
+            console.info(`[NavRouterPlugin] 已注入 module.json5 routerMap = "${profileRef}" (${moduleName})`);
+          }
+        }
+      });
+    },
+  };
+}
+
+/** 供 HAP 模块（entry）的 hvigorfile.ts 使用 */
+export function navRouterHapPlugin(config?: PluginConfig): HvigorPlugin {
+  return createNavRouterPlugin(OhosPluginId.OHOS_HAP_PLUGIN, config);
+}
+
+/** 供 HAR 模块（features/*）的 hvigorfile.ts 使用 */
+export function navRouterHarPlugin(config?: PluginConfig): HvigorPlugin {
+  return createNavRouterPlugin(OhosPluginId.OHOS_HAR_PLUGIN, config);
+}

package/src/scanner.ts

@@ -0,0 +1,479 @@
+/**
+ * @leejung/hvigor-nav-router-plugin — AST 路由扫描器
+ *
+ * 基于 ts-morph 扫描 .ets 源文件中的路由声明，
+ * 提取路由信息并解析常量引用，生成 RouteMapEntry 列表。
+ *
+ * 当前仓库的主方案是：
+ *
+ *   1. 路由名由 `PageConstants` 统一导出
+ *   2. 页面文件只保留 `@Builder export function XxxBuilder()`
+ *   3. 插件优先按 Builder 名在中央常量表中找路由，找不到再按目录规则兜底
+ *
+ * 保留对 `@NavRoute({ url: ... })` / `NAV_ROUTE_NAME` 的解析能力，仅作为兼容兜底。
+ * ArkTS 当前不允许在 `@Builder` 函数上挂自定义装饰器，因此业务代码不使用该写法。
+ *
+ * 路由名获取优先级：
+ *   1. `@NavRoute({ url: ... })` 装饰器（保留解析能力，支持字符串字面量和常量引用）
+ *   2. `// @NavRoute({ url: '...' })` 注释（向后兼容）
+ *   3. `export const NAV_ROUTE_NAME = ...` 常量（兼容旧写法）
+ *   4. `PageConstants` 中央常量映射
+ *   5. 文件路径推导（pages/ → page://，dialogs/ → dialog://）
+ *
+ * 参考 @hadss/hmrouter-plugin 的 HMRouterAnalyzer 实现。
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import {
+  SyntaxKind,
+  Node,
+  SourceFile,
+  Decorator,
+  ObjectLiteralExpression,
+  PropertyAssignment,
+} from 'ts-morph';
+import { PluginConfig, RouteMapEntry } from './types';
+import {
+  getProject,
+  normalizeSlashes,
+  buildImportMap,
+  parseConstantValue,
+  resolveConstantFull,
+  ImportEntry,
+} from './ast-utils';
+
+const centralRouteCache = new Map<string, Map<string, string>>();
+
+/** 递归遍历目录，收集所有 .ets 文件 */
+function walkEtsFiles(dirPath: string): string[] {
+  if (!fs.existsSync(dirPath)) {
+    return [];
+  }
+  const result: string[] = [];
+  const entries = fs.readdirSync(dirPath, { withFileTypes: true });
+  for (const entry of entries) {
+    const fullPath = path.join(dirPath, entry.name);
+    if (entry.isDirectory()) {
+      result.push(...walkEtsFiles(fullPath));
+    } else if (entry.isFile() && entry.name.endsWith('.ets')) {
+      result.push(fullPath);
+    }
+  }
+  return result;
+}
+
+/** 从文件路径和 Builder 名推导默认路由名 */
+function buildDefaultRouteName(relativeSourceFile: string, buildFunction: string): string {
+  const normalized = normalizeSlashes(relativeSourceFile);
+  const builderBaseName = buildFunction.endsWith('Builder')
+    ? buildFunction.slice(0, -'Builder'.length)
+    : buildFunction;
+  const baseName = builderBaseName || path.basename(normalized, '.ets');
+  const prefix = normalized.includes('/dialogs/') ? 'dialog://' : 'page://';
+  return prefix + baseName;
+}
+
+function buildRouteBaseName(buildFunction: string): string {
+  return buildFunction.endsWith('Builder')
+    ? buildFunction.slice(0, -'Builder'.length)
+    : buildFunction;
+}
+
+function getPageConstantsCandidates(moduleDir: string): string[] {
+  const candidates = [
+    path.join(moduleDir, 'src', 'main', 'ets', 'constants', 'PageConstants.ets'),
+    path.resolve(moduleDir, '..', 'appcommon', 'src', 'main', 'ets', 'constants', 'PageConstants.ets'),
+    path.resolve(moduleDir, '..', '..', 'features', 'appcommon', 'src', 'main', 'ets', 'constants', 'PageConstants.ets'),
+    path.join(moduleDir, 'oh_modules', 'appcommon', 'src', 'main', 'ets', 'constants', 'PageConstants.ets'),
+  ];
+  return Array.from(new Set(candidates));
+}
+
+function loadCentralRouteMap(moduleDir: string): Map<string, string> {
+  const cached = centralRouteCache.get(moduleDir);
+  if (cached) {
+    return cached;
+  }
+
+  const routeMap = new Map<string, string>();
+  const project = getProject();
+  const candidates = getPageConstantsCandidates(moduleDir);
+  for (const candidate of candidates) {
+    if (!fs.existsSync(candidate)) {
+      continue;
+    }
+
+    let sourceFile = project.getSourceFile(candidate);
+    if (!sourceFile) {
+      sourceFile = project.addSourceFileAtPath(candidate);
+    }
+
+    const pageConstantsClass = sourceFile.getClass('PageConstants');
+    if (!pageConstantsClass) {
+      continue;
+    }
+
+    const staticProperties = pageConstantsClass.getStaticProperties();
+    for (const property of staticProperties) {
+      if (!Node.isPropertyDeclaration(property)) {
+        continue;
+      }
+      const propertyName = property.getName();
+      const initializer = property.getInitializer();
+      if (!initializer || !Node.isStringLiteral(initializer)) {
+        continue;
+      }
+      const routeName = initializer.getLiteralValue();
+      const match = routeName.match(/^[a-z]+:\/\/(.+)$/);
+      if (!match) {
+        continue;
+      }
+      const routeBaseName = match[1];
+      if (propertyName && !routeMap.has(propertyName)) {
+        routeMap.set(propertyName, routeName);
+      }
+      if (!routeMap.has(routeBaseName)) {
+        routeMap.set(routeBaseName, routeName);
+      }
+    }
+  }
+
+  centralRouteCache.set(moduleDir, routeMap);
+  return routeMap;
+}
+
+function resolveCentralRouteName(buildFunction: string, moduleDir: string): string | undefined {
+  const routeBaseName = buildRouteBaseName(buildFunction);
+  if (!routeBaseName) {
+    return undefined;
+  }
+  return loadCentralRouteMap(moduleDir).get(routeBaseName);
+}
+
+/** 检查路由表是否存在重复，发现重复时抛出错误 */
+function ensureNoDuplicate(entries: RouteMapEntry[], key: keyof RouteMapEntry, moduleDir: string): void {
+  const seen = new Map<string, RouteMapEntry>();
+  for (const entry of entries) {
+    const value = entry[key];
+    if (!value) {
+      continue;
+    }
+    const previous = seen.get(value);
+    if (previous) {
+      throw new Error(
+        `[NavRouterPlugin] 发现重复的 ${key} "${value}" (模块: ${moduleDir})\n` +
+        `  - ${previous.pageSourceFile}\n` +
+        `  - ${entry.pageSourceFile}`
+      );
+    }
+    seen.set(value, entry);
+  }
+}
+
+// ---- 正则兜底（用于 // @NavRoute 注释和 NAV_ROUTE_NAME） ----
+
+/** 匹配 @Builder + export function XxxBuilder( */
+const BUILDER_FUNCTION_RE = /@Builder[\s\r\n]*export function\s+([A-Za-z0-9_]*Builder)\s*\(/m;
+
+/** 匹配 // @NavRoute({ url: '...' }) 注释（向后兼容，仅匹配字符串字面量） */
+const NAV_ROUTE_COMMENT_RE = /\/\/\s*@NavRoute\s*\(\s*\{\s*url\s*:\s*['"]([^'"]+)['"]/m;
+
+/** 匹配 export const NAV_ROUTE_NAME = '...'（向后兼容） */
+const ROUTE_NAME_CONST_RE = /export const NAV_ROUTE_NAME\s*=\s*['"]([^'"]+)['"]/m;
+/** 匹配 export const NAV_ROUTE_NAME = xxx; 并提取完整右值表达式 */
+const ROUTE_NAME_EXPR_RE = /export const NAV_ROUTE_NAME\s*=\s*([^;\r\n]+)/m;
+
+
+// ---- AST 扫描核心逻辑 ----
+
+/**
+ * 在 MissingDeclaration 节点中查找 @NavRoute 装饰器
+ *
+ * ArkTS 的 @Builder export function 在 ts-morph 中被解析为 MissingDeclaration，
+ * @NavRoute 装饰器绑定在 @Builder 函数上：
+ *
+ *   @NavRoute({ url: PageConstants.Home })
+ *   @Builder
+ *   export function HomePageBuilder() { ... }
+ *
+ * 两个装饰器在同一个 MissingDeclaration 节点上，可通过 getDecorators() 获取。
+ */
+function findNavRouteDecorator(missingDecl: Node): Decorator | undefined {
+  const decorableNode = missingDecl as Node & {
+    getDecorators?: () => Decorator[];
+  };
+  if (typeof decorableNode.getDecorators !== 'function') {
+    return undefined;
+  }
+  const decorators = decorableNode.getDecorators();
+  for (const decorator of decorators) {
+    if (decorator.getName() === 'NavRoute') {
+      return decorator;
+    }
+  }
+  return undefined;
+}
+
+/**
+ * 从 @NavRoute 装饰器中提取 url 值
+ *
+ * 支持的形式:
+ * - @NavRoute({ url: 'page://HomePage' })            → 字符串字面量
+ * - @NavRoute({ url: PageConstants.Home })            → 类静态属性引用
+ * - @NavRoute({ url: HOME_URL })                      → 顶级常量引用
+ */
+function extractUrlFromDecorator(
+  decorator: Decorator,
+  sourceFile: SourceFile,
+  importMap: Map<string, ImportEntry>,
+  moduleDir: string
+): string | undefined {
+  const args = decorator.getArguments();
+  if (args.length === 0) {
+    return undefined;
+  }
+
+  const firstArg = args[0];
+  if (!Node.isObjectLiteralExpression(firstArg)) {
+    return undefined;
+  }
+
+  const urlProp = (firstArg as ObjectLiteralExpression).getProperty('url');
+  if (!urlProp || !Node.isPropertyAssignment(urlProp)) {
+    return undefined;
+  }
+
+  const initializer = (urlProp as PropertyAssignment).getInitializer();
+  if (!initializer) {
+    return undefined;
+  }
+
+  // Case 1: 字符串字面量
+  if (Node.isStringLiteral(initializer)) {
+    return initializer.getLiteralValue();
+  }
+
+  // Case 2: 属性访问 (PageConstants.Home)
+  if (Node.isPropertyAccessExpression(initializer)) {
+    const objectName = initializer.getExpression().getText();
+    const propName = initializer.getName();
+    return resolveIdentifierValue(objectName, propName, sourceFile, importMap, moduleDir);
+  }
+
+  // Case 3: 标识符 (HOME_URL)
+  if (Node.isIdentifier(initializer)) {
+    const varName = initializer.getText();
+    return resolveIdentifierValue(varName, undefined, sourceFile, importMap, moduleDir);
+  }
+
+  return undefined;
+}
+
+/**
+ * 解析标识符/属性访问引用的实际字符串值
+ */
+function resolveIdentifierValue(
+  variableName: string,
+  propertyName: string | undefined,
+  sourceFile: SourceFile,
+  importMap: Map<string, ImportEntry>,
+  moduleDir: string
+): string | undefined {
+  // 先尝试在当前文件中解析
+  const localValue = parseConstantValue(sourceFile, variableName, propertyName);
+  if (localValue !== undefined) {
+    return localValue;
+  }
+
+  // 通过 import 链跨文件解析
+  const importEntry = importMap.get(variableName);
+  if (!importEntry) {
+    return undefined;
+  }
+
+  const currentFileDir = path.dirname(sourceFile.getFilePath());
+  return resolveConstantFull(importEntry, variableName, propertyName, currentFileDir, moduleDir);
+}
+
+/**
+ * 从源码文本中的 NAV_ROUTE_NAME 右值表达式解析路由名
+ *
+ * 支持:
+ * - 'page://HomePage'
+ * - PageConstants.Home
+ * - HOME_URL
+ */
+function resolveRouteExpression(
+  expressionText: string,
+  sourceFile: SourceFile,
+  importMap: Map<string, ImportEntry>,
+  moduleDir: string
+): string | undefined {
+  const trimmed = expressionText.trim();
+  const stringMatch = trimmed.match(/^['"]([^'"]+)['"]$/);
+  if (stringMatch) {
+    return stringMatch[1];
+  }
+
+  const propertyMatch = trimmed.match(/^([A-Za-z_][A-Za-z0-9_]*)\.([A-Za-z_][A-Za-z0-9_]*)$/);
+  if (propertyMatch) {
+    return resolveIdentifierValue(propertyMatch[1], propertyMatch[2], sourceFile, importMap, moduleDir);
+  }
+
+  const identifierMatch = trimmed.match(/^([A-Za-z_][A-Za-z0-9_]*)$/);
+  if (identifierMatch) {
+    return resolveIdentifierValue(identifierMatch[1], undefined, sourceFile, importMap, moduleDir);
+  }
+
+  return undefined;
+}
+
+/**
+ * 从源文件中提取 @Builder export function XxxBuilder 的名称
+ */
+function findBuilderFunction(sourceFile: SourceFile, relativeSourceFile: string): string | undefined {
+  // ts-morph 对 ArkTS 的 @Builder 装饰器识别有限，使用正则更可靠
+  const content = sourceFile.getFullText();
+  const matches = Array.from(content.matchAll(new RegExp(BUILDER_FUNCTION_RE.source, 'g')));
+  if (matches.length === 0) {
+    return undefined;
+  }
+
+  const expectedBuilderName = `${path.basename(relativeSourceFile, '.ets')}Builder`;
+  const exactMatch = matches.find((match) => match[1] === expectedBuilderName);
+  return exactMatch?.[1] ?? matches[0][1];
+}
+
+/**
+ * 扫描单个 .ets 文件，提取路由信息
+ */
+function scanSingleFile(
+  etsFilePath: string,
+  moduleDir: string
+): RouteMapEntry | undefined {
+  const project = getProject();
+
+  // 读取文件内容
+  const content = fs.readFileSync(etsFilePath, 'utf8');
+
+  // 必须有 @Builder export function XxxBuilder 才是路由页面
+  if (!content.match(BUILDER_FUNCTION_RE)) {
+    return undefined;
+  }
+  const relativeSourceFile = normalizeSlashes(path.relative(moduleDir, etsFilePath));
+
+  // 添加到 ts-morph project
+  let sourceFile = project.getSourceFile(etsFilePath);
+  if (!sourceFile) {
+    sourceFile = project.addSourceFileAtPath(etsFilePath);
+  }
+
+  const buildFunction = findBuilderFunction(sourceFile, relativeSourceFile);
+  if (!buildFunction) {
+    return undefined;
+  }
+
+  // 构建 import 映射
+  const importMap = buildImportMap(sourceFile);
+
+  // 优先级 1: 查找 @NavRoute 装饰器（AST 方式）
+  let routeName: string | undefined;
+
+  const missingDecls = sourceFile.getChildrenOfKind(SyntaxKind.MissingDeclaration);
+  for (const missingDecl of missingDecls) {
+    const decorator = findNavRouteDecorator(missingDecl);
+    if (decorator) {
+      routeName = extractUrlFromDecorator(decorator, sourceFile, importMap, moduleDir);
+      break;
+    }
+  }
+
+  // 优先级 2: // @NavRoute 注释（向后兼容）
+  if (!routeName) {
+    const commentMatch = content.match(NAV_ROUTE_COMMENT_RE);
+    if (commentMatch) {
+      routeName = commentMatch[1];
+    }
+  }
+
+  // 优先级 3: export const NAV_ROUTE_NAME = ...（AST 解析，支持常量引用）
+  if (!routeName) {
+    const varDecl = sourceFile.getVariableDeclaration('NAV_ROUTE_NAME');
+    if (varDecl) {
+      const init = varDecl.getInitializer();
+      if (init) {
+        if (Node.isStringLiteral(init)) {
+          routeName = init.getLiteralValue();
+        } else if (Node.isPropertyAccessExpression(init)) {
+          const objName = init.getExpression().getText();
+          const propName = init.getName();
+          routeName = resolveIdentifierValue(objName, propName, sourceFile, importMap, moduleDir);
+        } else if (Node.isIdentifier(init)) {
+          routeName = resolveIdentifierValue(init.getText(), undefined, sourceFile, importMap, moduleDir);
+        }
+      }
+    }
+  }
+
+  // 优先级 3a: NAV_ROUTE_NAME 文本兜底（适配 ArkTS 场景下 ts-morph 取不到变量声明）
+  if (!routeName) {
+    const exprMatch = content.match(ROUTE_NAME_EXPR_RE);
+    if (exprMatch) {
+      routeName = resolveRouteExpression(exprMatch[1], sourceFile, importMap, moduleDir);
+    }
+  }
+
+  // 优先级 3b: NAV_ROUTE_NAME 正则兜底（仅字符串字面量）
+  if (!routeName) {
+    const constMatch = content.match(ROUTE_NAME_CONST_RE);
+    if (constMatch) {
+      routeName = constMatch[1];
+    }
+  }
+
+  // 优先级 4: 文件路径推导
+  if (!routeName) {
+    routeName = resolveCentralRouteName(buildFunction, moduleDir)
+      ?? buildDefaultRouteName(relativeSourceFile, buildFunction);
+  }
+
+  return { name: routeName, pageSourceFile: relativeSourceFile, buildFunction };
+}
+
+
+/**
+ * 扫描指定模块目录，返回排序后的路由表条目列表。
+ *
+ * @param moduleDir 模块根目录绝对路径
+ * @param config 插件配置
+ */
+export function scanRouteAnnotations(moduleDir: string, config?: PluginConfig): RouteMapEntry[] {
+  centralRouteCache.delete(moduleDir);
+  const scanDirs = config?.scanDirs ?? [
+    path.join('src', 'main', 'ets', 'pages'),
+    path.join('src', 'main', 'ets', 'dialogs'),
+  ];
+
+  const entries: RouteMapEntry[] = [];
+
+  for (const scanDir of scanDirs) {
+    const absoluteScanDir = path.join(moduleDir, scanDir);
+    const etsFiles = walkEtsFiles(absoluteScanDir);
+
+    for (const etsFile of etsFiles) {
+      const entry = scanSingleFile(etsFile, moduleDir);
+      if (entry) {
+        entries.push(entry);
+      }
+    }
+  }
+
+  // 按路由名排序，保证输出稳定
+  entries.sort((a, b) => a.name.localeCompare(b.name));
+
+  ensureNoDuplicate(entries, 'name', moduleDir);
+  ensureNoDuplicate(entries, 'buildFunction', moduleDir);
+
+  return entries;
+}

package/src/types.ts

@@ -0,0 +1,32 @@
+/**
+ * @leejung/hvigor-nav-router-plugin — 类型定义
+ */
+
+/** 一条路由表条目，对应 route_map.json 中 routerMap 数组的单个元素 */
+export interface RouteMapEntry {
+  /** 路由名，如 'page://HomePage' 或 'dialog://StopServerNoticeDialog' */
+  name: string;
+  /** 源文件相对于模块根目录的路径，如 'src/main/ets/pages/HomePage.ets' */
+  pageSourceFile: string;
+  /** 页面入口 Builder 函数名，如 'HomePageBuilder' */
+  buildFunction: string;
+}
+
+/** route_map.json 文件的根结构 */
+export interface RouteMapFile {
+  routerMap: RouteMapEntry[];
+}
+
+/** 插件配置项 */
+export interface PluginConfig {
+  /**
+   * 扫描目录列表（相对于模块根目录）。
+   * 默认值：['src/main/ets/pages', 'src/main/ets/dialogs']
+   */
+  scanDirs?: string[];
+  /**
+   * route_map.json 输出路径（相对于模块根目录）。
+   * 默认值：'src/main/resources/base/profile/route_map.json'
+   */
+  routeMapPath?: string;
+}

package/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ES2017",
+    "module": "commonjs",
+    "lib": ["ES2017"],
+    "strict": true,
+    "esModuleInterop": true,
+    "outDir": "dist",
+    "rootDir": "src",
+    "declaration": true,
+    "declarationDir": "dist",
+    "skipLibCheck": true
+  },
+  "include": ["src/**/*.ts"],
+  "exclude": ["node_modules", "dist"]
+}