vite-plugin-react-router-routecraft 0.0.0-stage → 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,15 @@
+# 更新记录
+
+本文件记录 Routecraft 的面向用户变更。
+
+## 0.1.1
+
+- 完善 AI 使用指南与 Skill 对已安装插件版本文档的定位说明，明确文档缺失或版本不匹配时的处理方式。
+
+## 0.1.0
+
+- 实现 Routecraft 目录约定到 React Router Data Mode `RouteObject[]` 的编译。
+- 支持多路由组与布局、动态段、末尾 splat、可选 loader/action、错误边界、HydrateFallback 和 middleware。
+- 支持按模块逐属性选择 eager/lazy，生成 `typed-router.d.ts` 和类型化 `href` 辅助接口。
+- 提供目录扫描诊断、Vite HMR、可选开发期 DevTools、中文使用指南和可构建示例。
+- 添加单元、集成、类型契约及覆盖率测试；升级到已审计修复的 Vitest 5.1.0。

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Routecraft contributors
+
+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/README.md

@@ -1,3 +1,102 @@
-# Temporary Holding Version
+# Routecraft
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**Routecraft** 是一个 Vite 插件：按约定目录生成 React Router v8 Data Mode 的 `RouteObject[]`，自动更新路由类型声明，并在开发期提供独立 DevTools 页面。
+
+> Routecraft 面向 React Router Data Mode；接入前请确认项目使用的 React Router 与 Vite 版本符合 peer dependency 要求。Routecraft 不实现 React Router Framework Mode，也不提供服务端鉴权或数据运行时。
+
+**文档站：**[Routecraft 文档](https://alon-wu.github.io/vite-plugin-react-router-routecraft/) · [完整示例](https://alon-wu.github.io/vite-plugin-react-router-routecraft/examples/complete-app) · [架构设计](https://alon-wu.github.io/vite-plugin-react-router-routecraft/architecture/)
+
+## 特性
+
+- 以目录表达路由层级，并通过 `page.tsx`、`layout.tsx` 等 Routecraft 约定文件生成路由对象；
+- 路由组 `(group)`、私有目录 `_private`、`[param]` 动态段及末尾 `[...parts]` splat；
+- 多分支、多布局；不同 route group 可各自拥有 layout；
+- 组件、loader、action、错误边界与 hydration fallback 逐属性选择 eager/lazy；
+- 不存在的 loader/action 不生成空属性或虚假导入；
+- 生成 `typed-router.d.ts`，声明路由 ID、URL 参数及类型化 `href` 辅助；
+- 可关闭的开发期路由树、加载方式和诊断 UI。
+
+## 仓库内文档
+
+- [灵机一动：项目起点与原始设计方案](docs/design/routecraft-design.md)
+- [配置指南](docs/guides/configuration.md)
+- [目录路由约定](docs/guides/routing-conventions.md)
+- [AI 编码助手](docs/guides/ai-assistants.md)
+- [DevTools 指南](docs/guides/devtools.md)
+
+## 试用示例
+
+仓库中的 `examples/basic` 是用于插件自动化验证的精简夹具，不是完整产品教程。完整、具体的应用级示例请阅读[项目管理台完整示例](https://alon-wu.github.io/vite-plugin-react-router-routecraft/examples/complete-app)。
+
+从源码运行仓库内的集成示例：
+
+```sh
+npm install
+npm run build
+cd examples/basic
+npm install
+npm run dev
+```
+
+打开 Vite 地址查看应用；开发服务器运行时可在同一主机打开 `/__routecraft` 查看路由树和诊断。应用路由入口使用方式：
+
+```tsx
+import { createBrowserRouter } from "react-router";
+import { RouterProvider } from "react-router/dom";
+import { routeObjects } from "virtual:routecraft/routes";
+
+const router = createBrowserRouter(routeObjects);
+```
+
+`virtual:routecraft/routes` 是 Routecraft 插件提供的 Vite 虚拟模块，不是 React Router 自带 API。Vite 的 `resolveId`/`load` 钩子将该导入编译为当前路由树；TypeScript 声明则写入配置的 typesDir。
+
+## 在 Vite 项目中配置
+
+```ts
+import { defineConfig } from "vite";
+import react from "@vitejs/plugin-react";
+import routecraft from "vite-plugin-react-router-routecraft";
+
+export default defineConfig({
+  plugins: [
+    react(),
+    routecraft({
+      routesDir: "src/routes",
+      typesDir: "src/types",
+      defaultLazy: true,
+      devTools: true,
+    }),
+  ],
+});
+```
+
+| 配置 | 默认值 | 说明 |
+| --- | --- | --- |
+| `routesDir` | `src/routes` | 相对于 Vite 项目根目录的路由根 |
+| `typesDir` | `src/types` | `typed-router.d.ts` 输出目录 |
+| `defaultLazy` | `true` | 约定模块的默认懒加载策略 |
+| `devTools` | `false` | 是否启用开发期 DevTools |
+
+## 开发与验证
+
+```sh
+npm install
+npm run typecheck
+npm test
+npm run test:coverage
+npm run build
+npm run pack:check
+```
+
+`npm run verify` 会执行类型检查、自动化测试和构建；`npm run pack:check` 仅预览 npm 包内容，不会发布。源代码注释与项目文档以中文编写。
+
+## 已知边界
+
+- `loading.tsx` 不会自动建立导航 loading UI；应用可用 React Router 的 `useNavigation()` 实现。
+- `hydrate-fallback.tsx` 映射为 React Router 的 `HydrateFallback`，用于 hydration fallback；它不是应用内导航状态组件。
+- 根 `middleware.ts` 位于共同合成路由根，影响所有分支。middleware 不是服务端安全边界。
+- `[...parts]` 映射为 React Router splat，参数通过 `params["*"]` 获取；`[[...parts]]` 不支持。
+- 不提供服务端组件、服务端操作、HTTP 请求处理器、并行/拦截式路由、框架级 metadata 或 Framework Mode typegen。
+- `useLoaderData()` 的业务返回值类型不做跨文件自动推导。
+
+详见[目录规则与语义边界](docs/guides/routing-conventions.md)。

package/dist/core/compile-routes.d.ts

@@ -0,0 +1,4 @@
+import type { RouteNode } from "./ir.js";
+/** 将 Route IR 编译为 Vite 虚拟模块可加载的 TypeScript 源码。 */
+export declare function compileRouteObjects(root: RouteNode): string;
+//# sourceMappingURL=compile-routes.d.ts.map

package/dist/core/compile-routes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compile-routes.d.ts","sourceRoot":"","sources":["../../src/core/compile-routes.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAGV,SAAS,EAEV,MAAM,SAAS,CAAC;AAEjB,kDAAkD;AAClD,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,SAAS,GAAG,MAAM,CAkB3D"}

package/dist/core/compile-routes.js

@@ -0,0 +1,71 @@
+/** 将 Route IR 编译为 Vite 虚拟模块可加载的 TypeScript 源码。 */
+export function compileRouteObjects(root) {
+    const modules = collectModules(root);
+    const imports = modules.map((module, index) => `import * as __routecraft_module_${index} from ${JSON.stringify(module.file)};`);
+    const moduleIndexes = new Map(modules.map((module, index) => [module.file, index]));
+    const routeObjects = `[${compileNode(root, 1, moduleIndexes)}]`;
+    return [
+        "// 由 Routecraft 根据路由目录自动生成；请勿手工编辑。",
+        ...imports,
+        "",
+        `export const routeObjects = ${routeObjects};`,
+        "",
+    ].join("\n");
+}
+function compileNode(node, depth, moduleIndexes) {
+    const indentation = "  ".repeat(depth);
+    const childIndentation = "  ".repeat(depth + 1);
+    const fields = [`id: ${JSON.stringify(node.id)}`];
+    if (node.path !== undefined)
+        fields.push(`path: ${JSON.stringify(node.path)}`);
+    if (node.index)
+        fields.push("index: true");
+    const eagerModules = Object.values(node.modules).filter((module) => Boolean(module && !module.lazy));
+    for (const module of eagerModules) {
+        fields.push(`${module.property}: ${moduleReference(module, moduleIndexes)}.${module.exportName}`);
+    }
+    if (node.middleware) {
+        fields.push(`middleware: [${middlewareReference(node.middleware, moduleIndexes)}.middleware]`);
+    }
+    const lazyModules = Object.values(node.modules).filter((module) => Boolean(module?.lazy));
+    if (lazyModules.length > 0) {
+        const lazyFields = lazyModules.map((module) => `${module.property}: async () => (await import(${JSON.stringify(module.file)})).${module.exportName}`);
+        fields.push(`lazy: { ${lazyFields.join(", ")} }`);
+    }
+    if (node.children.length > 0) {
+        const children = node.children
+            .map((child) => compileNode(child, depth + 2, moduleIndexes))
+            .join(",\n");
+        fields.push(`children: [\n${children}\n${childIndentation}]`);
+    }
+    return `{\n${fields.map((field) => `${childIndentation}${field}`).join(",\n")}\n${indentation}}`;
+}
+function collectModules(root) {
+    const byFile = new Map();
+    const visit = (node) => {
+        for (const module of Object.values(node.modules)) {
+            if (module && !module.lazy)
+                byFile.set(module.file, module);
+        }
+        if (node.middleware)
+            byFile.set(node.middleware.file, node.middleware);
+        for (const child of node.children)
+            visit(child);
+    };
+    visit(root);
+    return [...byFile.values()].sort((left, right) => left.file.localeCompare(right.file));
+}
+function moduleReference(module, moduleIndexes) {
+    const index = moduleIndexes.get(module.file);
+    if (index === undefined) {
+        throw new Error(`Routecraft 编译错误：找不到模块 ${module.file} 的导入编号。`);
+    }
+    return `__routecraft_module_${index}`;
+}
+function middlewareReference(module, moduleIndexes) {
+    const index = moduleIndexes.get(module.file);
+    if (index === undefined) {
+        throw new Error(`Routecraft 编译错误：找不到 middleware 模块 ${module.file} 的导入编号。`);
+    }
+    return `__routecraft_module_${index}`;
+}

package/dist/core/config.d.ts

@@ -0,0 +1,11 @@
+import { type RoutecraftDiagnostic } from "./diagnostics.js";
+import type { RouteLazyConfig } from "../types.js";
+export interface ParsedRouteConfig {
+    lazy: RouteLazyConfig;
+    diagnostics: RoutecraftDiagnostic[];
+}
+/** 读取并静态分析目录配置；不执行用户模块。 */
+export declare function readRouteConfig(filePath: string): ParsedRouteConfig;
+/** 从源码直接解析静态配置，便于单元测试和调用方复用。 */
+export declare function parseRouteConfigSource(source: string, filePath?: string): ParsedRouteConfig;
+//# sourceMappingURL=config.d.ts.map

package/dist/core/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/core/config.ts"],"names":[],"mappings":"AAEA,OAAO,EAEL,KAAK,oBAAoB,EAC1B,MAAM,kBAAkB,CAAC;AAC1B,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAEnD,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,eAAe,CAAC;IACtB,WAAW,EAAE,oBAAoB,EAAE,CAAC;CACrC;AAaD,2BAA2B;AAC3B,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,iBAAiB,CAEnE;AAED,gCAAgC;AAChC,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,MAAM,EACd,QAAQ,SAAoB,GAC3B,iBAAiB,CAiJnB"}

package/dist/core/config.js

@@ -0,0 +1,104 @@
+import { readFileSync } from "node:fs";
+import ts from "typescript";
+import { errorDiagnostic, } from "./diagnostics.js";
+const supportedKeys = new Set([
+    "layout",
+    "layoutLoader",
+    "layoutAction",
+    "page",
+    "loader",
+    "action",
+    "error",
+    "hydrateFallback",
+]);
+/** 读取并静态分析目录配置；不执行用户模块。 */
+export function readRouteConfig(filePath) {
+    return parseRouteConfigSource(readFileSync(filePath, "utf8"), filePath);
+}
+/** 从源码直接解析静态配置，便于单元测试和调用方复用。 */
+export function parseRouteConfigSource(source, filePath = "route.config.ts") {
+    const sourceFile = ts.createSourceFile(filePath, source, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+    const diagnostics = [];
+    for (const statement of sourceFile.statements) {
+        if (ts.isImportDeclaration(statement) && !statement.importClause?.isTypeOnly) {
+            diagnostics.push(errorDiagnostic("RC_CONFIG_RUNTIME_IMPORT", "route.config.ts 仅允许 import type，不允许运行时导入。", filePath));
+        }
+    }
+    const assignment = sourceFile.statements.find((statement) => ts.isExportAssignment(statement) && !statement.isExportEquals);
+    if (!assignment) {
+        return {
+            lazy: {},
+            diagnostics: [
+                errorDiagnostic("RC_CONFIG_DEFAULT_EXPORT", "route.config.ts 必须默认导出一个静态配置对象。", filePath),
+            ],
+        };
+    }
+    const expression = unwrapExpression(assignment.expression);
+    if (!ts.isObjectLiteralExpression(expression)) {
+        return {
+            lazy: {},
+            diagnostics: [
+                errorDiagnostic("RC_CONFIG_STATIC_ONLY", "route.config.ts 的默认导出必须是对象字面量，不能使用变量、函数或运行时表达式。", filePath),
+            ],
+        };
+    }
+    const lazyProperty = expression.properties.find((property) => ts.isPropertyAssignment(property) && getPropertyName(property.name) === "lazy");
+    if (expression.properties.filter((property) => getPropertyName(property.name) === "lazy").length > 1) {
+        diagnostics.push(errorDiagnostic("RC_CONFIG_DUPLICATE_KEY", "route.config.ts 中 lazy 配置项不能重复。", filePath));
+    }
+    const otherProperties = expression.properties.filter((property) => getPropertyName(property.name) !== "lazy");
+    if (otherProperties.length > 0) {
+        diagnostics.push(errorDiagnostic("RC_CONFIG_UNKNOWN_KEY", `不支持 route.config.ts 配置项：${otherProperties
+            .map((property) => getPropertyName(property.name) ?? "未知属性")
+            .join(", ")}。`, filePath));
+    }
+    if (!lazyProperty)
+        return { lazy: {}, diagnostics };
+    const lazyExpression = unwrapExpression(lazyProperty.initializer);
+    if (!ts.isObjectLiteralExpression(lazyExpression)) {
+        diagnostics.push(errorDiagnostic("RC_CONFIG_LAZY_OBJECT", "route.config.ts 的 lazy 配置必须是对象字面量。", filePath));
+        return { lazy: {}, diagnostics };
+    }
+    const lazy = {};
+    const seenKeys = new Set();
+    for (const property of lazyExpression.properties) {
+        if (!ts.isPropertyAssignment(property)) {
+            diagnostics.push(errorDiagnostic("RC_CONFIG_STATIC_ONLY", "lazy 配置仅支持直接的布尔属性，不支持展开、方法或访问器。", filePath));
+            continue;
+        }
+        const name = getPropertyName(property.name);
+        if (!name || !supportedKeys.has(name)) {
+            diagnostics.push(errorDiagnostic("RC_CONFIG_UNKNOWN_KEY", `不支持 lazy 配置项“${name ?? "未知属性"}”。`, filePath));
+            continue;
+        }
+        if (seenKeys.has(name)) {
+            diagnostics.push(errorDiagnostic("RC_CONFIG_DUPLICATE_KEY", `lazy 配置项“${name}”不能重复。`, filePath));
+            continue;
+        }
+        seenKeys.add(name);
+        const value = unwrapExpression(property.initializer);
+        if (value.kind !== ts.SyntaxKind.TrueKeyword && value.kind !== ts.SyntaxKind.FalseKeyword) {
+            diagnostics.push(errorDiagnostic("RC_CONFIG_BOOLEAN", `lazy.${name} 必须是 true 或 false 字面量。`, filePath));
+            continue;
+        }
+        lazy[name] = value.kind === ts.SyntaxKind.TrueKeyword;
+    }
+    return { lazy, diagnostics };
+}
+function unwrapExpression(expression) {
+    if (ts.isParenthesizedExpression(expression) ||
+        ts.isAsExpression(expression) ||
+        ts.isTypeAssertionExpression(expression) ||
+        ts.isSatisfiesExpression(expression)) {
+        return unwrapExpression(expression.expression);
+    }
+    return expression;
+}
+function getPropertyName(name) {
+    if (!name)
+        return undefined;
+    if (ts.isIdentifier(name) || ts.isStringLiteral(name) || ts.isNumericLiteral(name)) {
+        return name.text;
+    }
+    return undefined;
+}

package/dist/core/diagnostics.d.ts

@@ -0,0 +1,15 @@
+export type DiagnosticLevel = "error" | "warning" | "info";
+export interface RoutecraftDiagnostic {
+    code: string;
+    level: DiagnosticLevel;
+    message: string;
+    file?: string;
+    routePath?: string;
+    suggestion?: string;
+}
+export declare class RoutecraftError extends Error {
+    readonly diagnostics: RoutecraftDiagnostic[];
+    constructor(diagnostics: RoutecraftDiagnostic[]);
+}
+export declare function errorDiagnostic(code: string, message: string, file?: string): RoutecraftDiagnostic;
+//# sourceMappingURL=diagnostics.d.ts.map

package/dist/core/diagnostics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnostics.d.ts","sourceRoot":"","sources":["../../src/core/diagnostics.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,eAAe,GAAG,OAAO,GAAG,SAAS,GAAG,MAAM,CAAC;AAE3D,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,eAAe,CAAC;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,qBAAa,eAAgB,SAAQ,KAAK;IACxC,QAAQ,CAAC,WAAW,EAAE,oBAAoB,EAAE,CAAC;gBAEjC,WAAW,EAAE,oBAAoB,EAAE;CAKhD;AAED,wBAAgB,eAAe,CAC7B,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,IAAI,CAAC,EAAE,MAAM,GACZ,oBAAoB,CAOtB"}

package/dist/core/diagnostics.js

@@ -0,0 +1,16 @@
+export class RoutecraftError extends Error {
+    diagnostics;
+    constructor(diagnostics) {
+        super(diagnostics.map((item) => `${item.code}: ${item.message}`).join("\n"));
+        this.name = "RoutecraftError";
+        this.diagnostics = diagnostics;
+    }
+}
+export function errorDiagnostic(code, message, file) {
+    return {
+        code,
+        level: "error",
+        message,
+        ...(file === undefined ? {} : { file }),
+    };
+}

package/dist/core/exports.d.ts

@@ -0,0 +1,4 @@
+import { type RoutecraftDiagnostic } from "./diagnostics.js";
+/** 通过 TypeScript AST 检查所需导出，不执行用户模块代码。 */
+export declare function analyzeModuleExports(source: string, filePath: string, requiredExports: readonly string[]): RoutecraftDiagnostic[];
+//# sourceMappingURL=exports.d.ts.map

package/dist/core/exports.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"exports.d.ts","sourceRoot":"","sources":["../../src/core/exports.ts"],"names":[],"mappings":"AACA,OAAO,EAEL,KAAK,oBAAoB,EAC1B,MAAM,kBAAkB,CAAC;AAE1B,0CAA0C;AAC1C,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,EAChB,eAAe,EAAE,SAAS,MAAM,EAAE,GACjC,oBAAoB,EAAE,CAmBxB"}

package/dist/core/exports.js

@@ -0,0 +1,51 @@
+import ts from "typescript";
+import { errorDiagnostic, } from "./diagnostics.js";
+/** 通过 TypeScript AST 检查所需导出，不执行用户模块代码。 */
+export function analyzeModuleExports(source, filePath, requiredExports) {
+    const sourceFile = ts.createSourceFile(filePath, source, ts.ScriptTarget.Latest, true, filePath.endsWith(".tsx") ? ts.ScriptKind.TSX : ts.ScriptKind.TS);
+    const exports = collectExports(sourceFile);
+    return requiredExports
+        .filter((name) => !exports.has(name))
+        .map((name) => errorDiagnostic("RC_REQUIRED_EXPORT", `路由模块必须导出“${name}”。`, filePath));
+}
+function collectExports(sourceFile) {
+    const exports = new Set();
+    for (const statement of sourceFile.statements) {
+        if (ts.isExportAssignment(statement) && !statement.isExportEquals) {
+            exports.add("default");
+            continue;
+        }
+        if (ts.isFunctionDeclaration(statement) || ts.isClassDeclaration(statement)) {
+            if (!hasModifier(statement, ts.SyntaxKind.ExportKeyword))
+                continue;
+            if (hasModifier(statement, ts.SyntaxKind.DefaultKeyword)) {
+                exports.add("default");
+            }
+            else if (statement.name) {
+                exports.add(statement.name.text);
+            }
+            continue;
+        }
+        if (ts.isVariableStatement(statement)) {
+            if (!hasModifier(statement, ts.SyntaxKind.ExportKeyword))
+                continue;
+            for (const declaration of statement.declarationList.declarations) {
+                if (ts.isIdentifier(declaration.name))
+                    exports.add(declaration.name.text);
+            }
+            continue;
+        }
+        if (ts.isExportDeclaration(statement) && statement.exportClause) {
+            if (ts.isNamedExports(statement.exportClause)) {
+                for (const element of statement.exportClause.elements) {
+                    exports.add(element.name.text);
+                }
+            }
+        }
+    }
+    return exports;
+}
+function hasModifier(node, kind) {
+    return (ts.canHaveModifiers(node) &&
+        (ts.getModifiers(node)?.some((modifier) => modifier.kind === kind) ?? false));
+}

package/dist/core/generate-types.d.ts

@@ -0,0 +1,4 @@
+import type { RouteIR } from "./ir.js";
+/** 根据同一份 Route IR 生成虚拟模块声明和类型化 href 契约。 */
+export declare function generateTypedRouter(ir: RouteIR): string;
+//# sourceMappingURL=generate-types.d.ts.map

package/dist/core/generate-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generate-types.d.ts","sourceRoot":"","sources":["../../src/core/generate-types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAa,MAAM,SAAS,CAAC;AAElD,2CAA2C;AAC3C,wBAAgB,mBAAmB,CAAC,EAAE,EAAE,OAAO,GAAG,MAAM,CAgCvD"}

package/dist/core/generate-types.js

@@ -0,0 +1,65 @@
+/** 根据同一份 Route IR 生成虚拟模块声明和类型化 href 契约。 */
+export function generateTypedRouter(ir) {
+    const routePaths = collectPagePaths(ir.root);
+    const routeIds = [...new Set(ir.routeIds)].sort();
+    const paramEntries = routePaths
+        .map((path) => `    ${JSON.stringify(path)}: ${formatParams(path)};`)
+        .join("\n");
+    return [
+        "// Routecraft 自动生成的声明文件；请勿手工编辑。",
+        'declare module "virtual:routecraft/routes" {',
+        '  import type { RouteObject } from "react-router";',
+        "",
+        "  export const routeObjects: RouteObject[];",
+        `  export type RouteId = ${union(routeIds)};`,
+        `  export type RoutePath = ${union(routePaths)};`,
+        "",
+        "  type RouteParamMap = {",
+        paramEntries,
+        "  };",
+        "  export type ParamsFor<P extends RoutePath> = RouteParamMap[P];",
+        "}",
+        "",
+        'declare module "virtual:routecraft" {',
+        '  import type { ParamsFor, RoutePath } from "virtual:routecraft/routes";',
+        "",
+        "  export function href<P extends RoutePath>(",
+        "    path: P,",
+        "    ...args: keyof ParamsFor<P> extends never ? [] : [params: ParamsFor<P>]",
+        "  ): string;",
+        "}",
+        "",
+    ].join("\n");
+}
+function collectPagePaths(root) {
+    const paths = new Set();
+    const visit = (node) => {
+        if (node.kind === "index")
+            paths.add(node.routePath);
+        for (const child of node.children)
+            visit(child);
+    };
+    visit(root);
+    return [...paths].sort();
+}
+function formatParams(path) {
+    const parameters = path
+        .split("/")
+        .flatMap((part) => {
+        if (part.startsWith(":"))
+            return [part.slice(1)];
+        if (part === "*")
+            return ["*"];
+        return [];
+    });
+    if (parameters.length === 0)
+        return "{}";
+    return `{ ${parameters
+        .map((parameter) => `${JSON.stringify(parameter)}: string`)
+        .join("; ")} }`;
+}
+function union(values) {
+    return values.length === 0
+        ? "never"
+        : values.map((value) => JSON.stringify(value)).join(" | ");
+}

package/dist/core/ir.d.ts

@@ -0,0 +1,31 @@
+import type { RoutecraftDiagnostic } from "./diagnostics.js";
+export type RouteNodeKind = "root" | "segment" | "index" | "not-found";
+export type RouteProperty = "Component" | "loader" | "action" | "ErrorBoundary" | "HydrateFallback";
+export interface RouteModuleRef {
+    file: string;
+    exportName: string;
+    property: RouteProperty;
+    lazy: boolean;
+}
+export interface MiddlewareModuleRef {
+    file: string;
+    exportName: "middleware";
+}
+export interface RouteNode {
+    id: string;
+    kind: RouteNodeKind;
+    sourcePath: string;
+    routePath: string;
+    path?: string;
+    index?: true;
+    modules: Partial<Record<RouteProperty, RouteModuleRef>>;
+    middleware?: MiddlewareModuleRef;
+    children: RouteNode[];
+}
+export interface RouteIR {
+    root: RouteNode;
+    routeIds: string[];
+    routePaths: string[];
+    diagnostics: RoutecraftDiagnostic[];
+}
+//# sourceMappingURL=ir.d.ts.map

package/dist/core/ir.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ir.d.ts","sourceRoot":"","sources":["../../src/core/ir.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAE7D,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,SAAS,GAAG,OAAO,GAAG,WAAW,CAAC;AACvE,MAAM,MAAM,aAAa,GACrB,WAAW,GACX,QAAQ,GACR,QAAQ,GACR,eAAe,GACf,iBAAiB,CAAC;AAEtB,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,aAAa,CAAC;IACxB,IAAI,EAAE,OAAO,CAAC;CACf;AAED,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,YAAY,CAAC;CAC1B;AAED,MAAM,WAAW,SAAS;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,aAAa,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,IAAI,CAAC;IACb,OAAO,EAAE,OAAO,CAAC,MAAM,CAAC,aAAa,EAAE,cAAc,CAAC,CAAC,CAAC;IACxD,UAAU,CAAC,EAAE,mBAAmB,CAAC;IACjC,QAAQ,EAAE,SAAS,EAAE,CAAC;CACvB;AAED,MAAM,WAAW,OAAO;IACtB,IAAI,EAAE,SAAS,CAAC;IAChB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,WAAW,EAAE,oBAAoB,EAAE,CAAC;CACrC"}

package/dist/core/ir.js

@@ -0,0 +1 @@
+export {};

package/dist/core/route-paths.d.ts

@@ -0,0 +1,3 @@
+/** 生成 href 虚拟模块源码；路径插值交由 React Router 原生实现。 */
+export declare function createHrefModuleSource(): string;
+//# sourceMappingURL=route-paths.d.ts.map

package/dist/core/route-paths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"route-paths.d.ts","sourceRoot":"","sources":["../../src/core/route-paths.ts"],"names":[],"mappings":"AAAA,+CAA+C;AAC/C,wBAAgB,sBAAsB,IAAI,MAAM,CAY/C"}

package/dist/core/route-paths.js

@@ -0,0 +1,14 @@
+/** 生成 href 虚拟模块源码；路径插值交由 React Router 原生实现。 */
+export function createHrefModuleSource() {
+    return [
+        "// Routecraft 路径辅助模块；路径规则由 React Router 处理。",
+        'import { generatePath } from "react-router";',
+        "",
+        "export function href(path, params) {",
+        "  return params === undefined",
+        "    ? generatePath(path)",
+        "    : generatePath(path, params);",
+        "}",
+        "",
+    ].join("\n");
+}

package/dist/core/route-tree.d.ts

@@ -0,0 +1,7 @@
+import type { RouteIR } from "./ir.js";
+export interface RouteTreeOptions {
+    defaultLazy: boolean;
+}
+/** 从扫描快照构建统一路由 IR，并校验模块契约与 URL 冲突。 */
+export declare function buildRouteTree(routesDir: string, options: RouteTreeOptions): RouteIR;
+//# sourceMappingURL=route-tree.d.ts.map

package/dist/core/route-tree.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"route-tree.d.ts","sourceRoot":"","sources":["../../src/core/route-tree.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAEV,OAAO,EAIR,MAAM,SAAS,CAAC;AAKjB,MAAM,WAAW,gBAAgB;IAC/B,WAAW,EAAE,OAAO,CAAC;CACtB;AAED,sCAAsC;AACtC,wBAAgB,cAAc,CAC5B,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,gBAAgB,GACxB,OAAO,CA+FT"}