@teardown/navigation-metro 2.0.43

package/src/index.ts

@@ -0,0 +1,158 @@
+/**
+ * @teardown/navigation-metro
+ * Metro plugin for type-safe file-based navigation
+ */
+
+import { resolve } from "node:path";
+import { generateAllRouteFiles } from "./generator/route-generator";
+import { startRouteWatcher } from "./watcher/file-watcher";
+
+/**
+ * Options for the Teardown Navigation Metro plugin
+ */
+export interface TeardownNavigationOptions {
+	/**
+	 * Path to routes directory relative to project root
+	 * @default './src/routes'
+	 */
+	routesDir?: string;
+
+	/**
+	 * Path for generated type files
+	 * @default './.teardown'
+	 */
+	generatedDir?: string;
+
+	/**
+	 * Deep link URL prefixes
+	 * @default []
+	 */
+	prefixes?: string[];
+
+	/**
+	 * Enable verbose logging
+	 * @default false
+	 */
+	verbose?: boolean;
+}
+
+/**
+ * Metro configuration type (simplified)
+ * Full type from metro-config can be used if available
+ */
+export interface MetroConfig {
+	projectRoot?: string;
+	watchFolders?: string[];
+	resolver?: {
+		resolveRequest?: (
+			context: unknown,
+			moduleName: string,
+			platform: string | null
+		) => { filePath: string; type: string } | null;
+		[key: string]: unknown;
+	};
+	transformer?: {
+		unstable_allowRequireContext?: boolean;
+		[key: string]: unknown;
+	};
+	[key: string]: unknown;
+}
+
+/**
+ * Wraps a Metro configuration with Teardown Navigation support
+ *
+ * This function:
+ * 1. Generates TypeScript type definitions on startup
+ * 2. Watches for route file changes in development
+ * 3. Configures Metro to include generated files
+ *
+ * @example
+ * ```js
+ * // metro.config.js
+ * const { getDefaultConfig } = require('expo/metro-config');
+ * const { withTeardownNavigation } = require('@teardown/navigation-metro');
+ *
+ * const config = getDefaultConfig(__dirname);
+ *
+ * module.exports = withTeardownNavigation(config, {
+ *   routesDir: './src/routes',
+ *   generatedDir: './.teardown',
+ *   prefixes: ['myapp://', 'https://myapp.com'],
+ *   verbose: true,
+ * });
+ * ```
+ */
+export function withTeardownNavigation(config: MetroConfig, options: TeardownNavigationOptions = {}): MetroConfig {
+	const { routesDir = "./src/routes", generatedDir = "./.teardown", prefixes = [], verbose = false } = options;
+
+	const projectRoot = config.projectRoot ?? process.cwd();
+	const absoluteRoutesDir = resolve(projectRoot, routesDir);
+	const absoluteGeneratedDir = resolve(projectRoot, generatedDir);
+
+	// Generate types on startup
+	try {
+		generateAllRouteFiles({
+			routesDir: absoluteRoutesDir,
+			generatedDir: absoluteGeneratedDir,
+			prefixes,
+			verbose,
+		});
+
+		if (verbose) {
+			console.log("[teardown/navigation] Initial generation complete");
+		}
+	} catch (error) {
+		console.error("[teardown/navigation] Initial generation failed:", error);
+	}
+
+	// Start file watcher in development
+	if (process.env.NODE_ENV !== "production") {
+		startRouteWatcher({
+			routesDir: absoluteRoutesDir,
+			generatedDir: absoluteGeneratedDir,
+			prefixes,
+			verbose,
+			onRegenerate: () => {
+				if (verbose) {
+					console.log("[teardown/navigation] Routes regenerated");
+				}
+			},
+			onError: (_errors) => {
+				if (verbose) {
+					console.error("[teardown/navigation] Validation errors during watch");
+				}
+			},
+		});
+	}
+
+	// Add watch folders for Metro
+	const watchFolders = [...(config.watchFolders ?? []), absoluteRoutesDir, absoluteGeneratedDir];
+
+	return {
+		...config,
+		watchFolders,
+		transformer: {
+			...config.transformer,
+			unstable_allowRequireContext: true,
+		},
+		resolver: {
+			...config.resolver,
+		},
+	};
+}
+
+export type { GenerateOptions, RouteParamEntry } from "./generator/route-generator";
+// Re-export modules
+export { generateAllRouteFiles } from "./generator/route-generator";
+export type { ParamDefinition, RouteNode, ScanError, ScanResult } from "./scanner/file-scanner";
+export {
+	buildUrlPath,
+	extractParams,
+	filePathToScreenName,
+	flattenRoutes,
+	scanRoutesDirectory,
+} from "./scanner/file-scanner";
+export type { ValidationError } from "./validator/route-validator";
+export { validateRoutes } from "./validator/route-validator";
+export type { WatcherOptions } from "./watcher/file-watcher";
+export { isWatcherRunning, startRouteWatcher, stopRouteWatcher } from "./watcher/file-watcher";

package/src/scanner/file-scanner.test.ts

@@ -0,0 +1,271 @@
+import { afterEach, beforeEach, describe, expect, it } from "bun:test";
+import { mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { buildUrlPath, extractParams, filePathToScreenName, type RouteNode, scanRoutesDirectory } from "./file-scanner";
+
+const TEST_DIR = join(import.meta.dir, "__test_routes__");
+
+function createTestFile(relativePath: string, content = "export default {}") {
+	const fullPath = join(TEST_DIR, relativePath);
+	const dir = fullPath.substring(0, fullPath.lastIndexOf("/"));
+	mkdirSync(dir, { recursive: true });
+	writeFileSync(fullPath, content);
+}
+
+describe("File Scanner", () => {
+	beforeEach(() => {
+		mkdirSync(TEST_DIR, { recursive: true });
+	});
+
+	afterEach(() => {
+		rmSync(TEST_DIR, { recursive: true, force: true });
+	});
+
+	describe("extractParams", () => {
+		it("should extract required param from [param]", () => {
+			const params = extractParams("[userId]");
+			expect(params).toEqual([{ name: "userId", isOptional: false, isCatchAll: false }]);
+		});
+
+		it("should extract optional param from [param]?", () => {
+			const params = extractParams("[section]?");
+			expect(params).toEqual([{ name: "section", isOptional: true, isCatchAll: false }]);
+		});
+
+		it("should extract catch-all param from [...slug]", () => {
+			const params = extractParams("[...slug]");
+			expect(params).toEqual([{ name: "slug", isOptional: false, isCatchAll: true }]);
+		});
+
+		it("should return empty array for static filename", () => {
+			const params = extractParams("about");
+			expect(params).toEqual([]);
+		});
+
+		it("should return empty array for index", () => {
+			const params = extractParams("index");
+			expect(params).toEqual([]);
+		});
+
+		it("should return empty array for _layout", () => {
+			const params = extractParams("_layout");
+			expect(params).toEqual([]);
+		});
+	});
+
+	describe("buildUrlPath", () => {
+		it("should build root path for index.tsx", () => {
+			const path = buildUrlPath("index.tsx", true, false);
+			expect(path).toBe("/");
+		});
+
+		it("should build static path", () => {
+			const path = buildUrlPath("about.tsx", false, false);
+			expect(path).toBe("/about");
+		});
+
+		it("should build nested path", () => {
+			const path = buildUrlPath("users/index.tsx", true, false);
+			expect(path).toBe("/users");
+		});
+
+		it("should build dynamic path with required param", () => {
+			const path = buildUrlPath("users/[userId].tsx", false, false);
+			expect(path).toBe("/users/:userId");
+		});
+
+		it("should build dynamic path with optional param", () => {
+			const path = buildUrlPath("settings/[section]?.tsx", false, false);
+			expect(path).toBe("/settings/:section?");
+		});
+
+		it("should build catch-all path", () => {
+			const path = buildUrlPath("docs/[...slug].tsx", false, false);
+			expect(path).toBe("/docs/*");
+		});
+
+		it("should remove route groups from path", () => {
+			const path = buildUrlPath("(tabs)/home.tsx", false, false);
+			expect(path).toBe("/home");
+		});
+
+		it("should return empty string for layout files", () => {
+			const path = buildUrlPath("_layout.tsx", false, true);
+			expect(path).toBe("");
+		});
+
+		it("should handle deeply nested dynamic paths", () => {
+			const path = buildUrlPath("users/[userId]/posts/[postId].tsx", false, false);
+			expect(path).toBe("/users/:userId/posts/:postId");
+		});
+	});
+
+	describe("filePathToScreenName", () => {
+		it("should convert file path to screen name", () => {
+			expect(filePathToScreenName("users/[userId].tsx")).toBe("users/[userId]");
+		});
+
+		it("should handle index files", () => {
+			expect(filePathToScreenName("users/index.tsx")).toBe("users/index");
+		});
+
+		it("should handle layout files", () => {
+			expect(filePathToScreenName("users/_layout.tsx")).toBe("users/_layout");
+		});
+	});
+
+	describe("scanRoutesDirectory", () => {
+		it("should return empty routes for non-existent directory", () => {
+			const result = scanRoutesDirectory("/non/existent/path");
+			expect(result.routes).toEqual([]);
+			expect(result.errors.length).toBeGreaterThan(0);
+		});
+
+		it("should scan single index file", () => {
+			createTestFile("index.tsx", "export default function Home() { return null; }");
+
+			const result = scanRoutesDirectory(TEST_DIR);
+			expect(result.errors).toEqual([]);
+			expect(result.routes.length).toBe(1);
+			expect(result.routes[0].path).toBe("/");
+			expect(result.routes[0].isIndex).toBe(true);
+		});
+
+		it("should scan static route file", () => {
+			createTestFile("about.tsx", "export default function About() { return null; }");
+
+			const result = scanRoutesDirectory(TEST_DIR);
+			expect(result.routes.length).toBe(1);
+			expect(result.routes[0].path).toBe("/about");
+			expect(result.routes[0].isIndex).toBe(false);
+		});
+
+		it("should scan dynamic route file", () => {
+			createTestFile("users/[userId].tsx", "export default function User() { return null; }");
+
+			const result = scanRoutesDirectory(TEST_DIR);
+			const userRoute = result.routes.find((r) => r.path === "/users/:userId");
+			expect(userRoute).toBeDefined();
+			expect(userRoute?.params).toEqual([{ name: "userId", isOptional: false, isCatchAll: false }]);
+		});
+
+		it("should scan layout files", () => {
+			createTestFile("_layout.tsx", "export default { type: 'stack' }");
+
+			const result = scanRoutesDirectory(TEST_DIR);
+			expect(result.routes.length).toBe(1);
+			expect(result.routes[0].isLayout).toBe(true);
+			expect(result.routes[0].layoutType).toBe("stack");
+		});
+
+		it("should scan tab layout files", () => {
+			createTestFile(
+				"(tabs)/_layout.tsx",
+				`
+        import { defineLayout } from '@teardown/navigation';
+        export default defineLayout({ type: 'tabs' });
+      `
+			);
+
+			const result = scanRoutesDirectory(TEST_DIR);
+			const tabLayout = result.routes.find((r) => r.isLayout && r.groupName === "tabs");
+			expect(tabLayout).toBeDefined();
+			expect(tabLayout?.layoutType).toBe("tabs");
+		});
+
+		it("should detect route groups", () => {
+			createTestFile("(auth)/login.tsx", "export default function Login() { return null; }");
+
+			const result = scanRoutesDirectory(TEST_DIR);
+			const loginRoute = result.routes.find((r) => r.path === "/login");
+			expect(loginRoute).toBeDefined();
+			expect(loginRoute?.groupName).toBe("auth");
+		});
+
+		it("should ignore hidden files starting with underscore (except _layout)", () => {
+			createTestFile("_hidden.tsx", "export default {}");
+			createTestFile("about.tsx", "export default {}");
+
+			const result = scanRoutesDirectory(TEST_DIR);
+			expect(result.routes.length).toBe(1);
+			expect(result.routes[0].path).toBe("/about");
+		});
+
+		it("should ignore test files", () => {
+			createTestFile("about.test.tsx", "export default {}");
+			createTestFile("about.tsx", "export default {}");
+
+			const result = scanRoutesDirectory(TEST_DIR);
+			expect(result.routes.length).toBe(1);
+			expect(result.routes[0].path).toBe("/about");
+		});
+
+		it("should scan catch-all routes", () => {
+			createTestFile("[...catchAll].tsx", "export default function CatchAll() { return null; }");
+
+			const result = scanRoutesDirectory(TEST_DIR);
+			expect(result.routes.length).toBe(1);
+			expect(result.routes[0].path).toBe("/*");
+			expect(result.routes[0].isCatchAll).toBe(true);
+			expect(result.routes[0].params).toEqual([{ name: "catchAll", isOptional: false, isCatchAll: true }]);
+		});
+
+		it("should build route tree with parent-child relationships", () => {
+			createTestFile("users/_layout.tsx", "export default { type: 'stack' }");
+			createTestFile("users/index.tsx", "export default {}");
+			createTestFile("users/[userId].tsx", "export default {}");
+
+			const result = scanRoutesDirectory(TEST_DIR);
+
+			// Find the layout
+			const layout = result.routes.find((r) => r.isLayout && r.relativePath.includes("users"));
+			expect(layout).toBeDefined();
+			expect(layout?.children.length).toBe(2);
+
+			// Children should be index and [userId]
+			const childPaths = layout?.children.map((c) => c.path) || [];
+			expect(childPaths).toContain("/users");
+			expect(childPaths).toContain("/users/:userId");
+		});
+
+		it("should handle complex nested structure", () => {
+			createTestFile("_layout.tsx", "export default { type: 'stack' }");
+			createTestFile("index.tsx", "export default {}");
+			createTestFile("about.tsx", "export default {}");
+			createTestFile("users/_layout.tsx", "export default { type: 'stack' }");
+			createTestFile("users/index.tsx", "export default {}");
+			createTestFile("users/[userId].tsx", "export default {}");
+			createTestFile("users/[userId]/posts/[postId].tsx", "export default {}");
+			createTestFile("(tabs)/_layout.tsx", "export default { type: 'tabs' }");
+			createTestFile("(tabs)/home.tsx", "export default {}");
+			createTestFile("(tabs)/settings.tsx", "export default {}");
+
+			const result = scanRoutesDirectory(TEST_DIR);
+
+			// Should have root layout with children
+			const rootLayout = result.routes.find((r) => r.isLayout && r.relativePath === "_layout.tsx");
+			expect(rootLayout).toBeDefined();
+
+			// Flatten all routes for easier checking
+			const allRoutes = flattenRoutes(result.routes);
+			const allPaths = allRoutes.filter((r) => !r.isLayout).map((r) => r.path);
+
+			expect(allPaths).toContain("/");
+			expect(allPaths).toContain("/about");
+			expect(allPaths).toContain("/users");
+			expect(allPaths).toContain("/users/:userId");
+			expect(allPaths).toContain("/users/:userId/posts/:postId");
+			expect(allPaths).toContain("/home");
+			expect(allPaths).toContain("/settings");
+		});
+	});
+});
+
+function flattenRoutes(routes: RouteNode[]): RouteNode[] {
+	const result: RouteNode[] = [];
+	for (const route of routes) {
+		result.push(route);
+		result.push(...flattenRoutes(route.children));
+	}
+	return result;
+}