文件路由

/**
 * 创建文件路由管理器
 * @param options - 配置选项
 * @param init - 是否在构造时扫描页面目录，默认 true
 */
new FileRouter(options?: FileRouterOptions, init?: boolean)

/**
 * 生成路由代码和类型定义
 * @returns 生成结果，包含 routes、code、dts
 */
fileRouter.generate(): GenerateResult

/**
 * 重新加载所有页面
 * @returns 当前实例，支持链式调用
 */
fileRouter.reload(): this

fileRouter.clearGenerateResult(): void

/**
 * 检查文件是否为页面文件
 * @param file - 文件绝对路径
 * @param filter - 可选的过滤配置，覆盖默认的 config.pages
 * @returns 是否为页面文件
 */
fileRouter.isPageFile(file: string, filter?: FilterOptions | readonly FilterOptions[]): boolean

/**
 * 获取文件的完整路由路径
 * @param filePath - 文件绝对路径
 * @returns 完整路由路径，非页面文件返回 null
 */
fileRouter.getRouteFullPath(filePath: string): string | null

/**
 * 添加页面文件到路由树
 * @param filePath - 文件绝对路径
 * @returns 是否创建了新的路由节点
 */
fileRouter.addPage(filePath: string): boolean

/**
 * 移除指定的文件或目录
 * @param filePath - 文件/目录绝对路径
 * @returns 存在则移除并返回 true，不存在返回 false
 */
fileRouter.removePage(filePath: string): boolean

/**
 * 更新文件
 * @param filePath - 文件绝对路径
 * @returns 是否更新了路由
 */
fileRouter.updatePage(filePath: string): boolean

/**
 * 处理文件变化事件
 * @param eventName - 文件变化事件名
 * @param path - 文件路径
 * @returns 是否影响了路由
 */
fileRouter.handleChange(eventName: FileWatcherEvent, path: string): boolean

/**
 * 移除 definePage 宏调用
 * @param code - 源代码
 * @param filePath - 文件路径
 * @returns 转换后的代码，无需转换返回 null
 */
fileRouter.removeDefinePage(code: string, filePath: string): GeneratorResult | null

import { FileRouter } from 'vitarx-router/file-router'

// 创建实例并自动扫描
const router = new FileRouter({
  root: process.cwd(),
  pages: 'src/pages',
  pathStrategy: 'kebab',
  importMode: 'lazy',
  dts: 'typed-router.d.ts',
  extendRoute(route) {
    route.meta ??= { auth: true }
  }
})

// 生成路由代码
const result = router.generate()
console.log(result.code) // 路由配置代码
console.log(result.routes) // 路由节点数组

// 增量更新
router.addPage('/src/pages/new-page.tsx')
router.removePage('/src/pages/old-page.tsx')
router.handleChange('change', '/src/pages/home.tsx')

// 重新加载
router.reload()

interface FileRouterOptions {
  root?: string
  pages?: PageSource | readonly PageSource[]
  pathStrategy?: PathStrategy
  importMode?: ImportMode
  dts?: boolean | string
  layoutFileName?: string
  configFileName?: string
  injectImports?: readonly string[]
  transform?: CodeTransformHook
  extendRoute?: ExtendRouteHook
  beforeWriteRoutes?: BeforeWriteRoutesHook
  pageParser?: PageParser
  groupParser?: GroupParser
}

interface PageDirOptions {
  dir: string
  include?: readonly string[]
  exclude?: readonly string[]
  prefix?: string
  group?: boolean
}

interface PageOptions {
  name?: string
  meta?: RouteMetaData
  pattern?: Record<string, RegExp>
  redirect?: string | RedirectConfig
  alias?: string | string[]
}

interface ScanNode {
  dirConfigFile?: string
  readonly isGroup: boolean
  readonly filePath: string
  readonly path: string
  parent?: ScanNode
  children?: Set<ScanNode>
  components?: Record<string, string>
  options?: PageOptions
}

interface RouteNode extends PageOptions {
  isGroup: boolean
  filePath: string
  path: string
  fullPath: string
  children?: RouteNode[]
  component?: Record<string, string>
}

type ExtendRouteHook = (route: RouteNode) => void

{
  extendRoute(route) {
    if (route.path === '/admin') {
      route.meta ??= { auth: true }
    }
  }
}

type BeforeWriteRoutesHook = (routes: RouteNode[]) => void | RouteNode[]

{
  beforeWriteRoutes(routes) {
    routes.forEach(route => {
      if (route.path === '/') {
        route.path = '/home'
      }
    })
  }
}

type CodeTransformHook = (content: string, file: string) => string

{
  transform(content, file) {
    if (file.endsWith('.md')) {
      const html = markdownToHtml(content)
      return `export default function Page() { return #123;html} }`
    }
    return content
  }
}

type PageParser = (basename: string, filePath: string) => string | PageParseResult

{
  pageParser(basename, filePath) {
    // 移除文件名中的数字前缀
    return basename.replace(/^d+./, '')
  }
}

type GroupParser = (dirName: string, dirPath: string) => string | GroupParseResult

{
  groupParser(dirName) {
    const result = parseOrderAndName(dirName) // 如 '1.admin' → { order: 1, name: 'admin' }
    return {
      path: result.name,
      options: { meta: { order: result.order } }
    }
  }
}

type ComponentImportHandler = (context: ImportModeContext) => 'lazy' | 'sync' | string

{
  importMode(context) {
    context.addImport(`import { lazy } from 'vitarx'`)
    return `lazy(() => import(#123;context.importPath}))`
  }
}

function definePage(options: PageOptions): void

definePage({
  pattern: {
    id: /^[0-9]+$/ // id 参数只匹配数字
  }
})

// 字符串格式
definePage({ redirect: '/new-path' })

// 对象格式
definePage({
  redirect: {
    index: '/user',
    params: { id: '1' },
    query: { tab: 'info' }
  }
})

// src/pages/user/[id].tsx
definePage({
  name: 'userDetail',
  meta: { title: '用户详情', auth: true },
  pattern: { id: /^[0-9]+$/ },
  alias: ['/u/{id}']
})

export default function UserDetail() {
  return <div>用户详情</div>
}

// src/pages/old-page.tsx
definePage({
  redirect: '/new-page'
})

export default function OldPage() {
  return <div>已重定向</div>
}