@teardown/navigation-metro 2.0.43

package/src/scanner/file-scanner.ts

@@ -0,0 +1,329 @@
+/**
+ * File scanner for @teardown/navigation-metro
+ * Scans routes directory and builds a route tree for type generation
+ */
+
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { basename, dirname, extname, join } from "node:path";
+
+export interface RouteNode {
+	/** Screen name derived from file path */
+	name: string;
+	/** URL path for this route */
+	path: string;
+	/** Absolute file path */
+	filePath: string;
+	/** Relative file path from routes dir */
+	relativePath: string;
+	/** Extracted dynamic params */
+	params: ParamDefinition[];
+	/** Child routes */
+	children: RouteNode[];
+	/** Navigator type from _layout.tsx */
+	layoutType: "stack" | "tabs" | "drawer" | "none";
+	/** Is this an index route */
+	isIndex: boolean;
+	/** Is this a layout file */
+	isLayout: boolean;
+	/** Is this a catch-all route */
+	isCatchAll: boolean;
+	/** Route group name (from parentheses) */
+	groupName: string | null;
+}
+
+export interface ParamDefinition {
+	name: string;
+	isOptional: boolean;
+	isCatchAll: boolean;
+}
+
+export interface ScanResult {
+	routes: RouteNode[];
+	errors: ScanError[];
+}
+
+export interface ScanError {
+	file: string;
+	message: string;
+}
+
+/**
+ * Scans a routes directory and builds a route tree
+ */
+export function scanRoutesDirectory(routesDir: string): ScanResult {
+	const errors: ScanError[] = [];
+
+	if (!existsSync(routesDir)) {
+		return {
+			routes: [],
+			errors: [{ file: routesDir, message: "Routes directory does not exist" }],
+		};
+	}
+
+	const files = findRouteFiles(routesDir);
+	const routeNodes = new Map<string, RouteNode>();
+
+	// First pass: create all route nodes
+	for (const file of files) {
+		const absolutePath = join(routesDir, file);
+		const node = parseRouteFile(file, absolutePath);
+
+		if (node) {
+			routeNodes.set(file, node);
+		}
+	}
+
+	// Second pass: build tree structure
+	const rootNodes: RouteNode[] = [];
+
+	for (const [filePath, node] of routeNodes) {
+		const parentPath = findParentLayoutPath(filePath, routeNodes);
+
+		if (parentPath) {
+			const parent = routeNodes.get(parentPath);
+			if (parent) {
+				parent.children.push(node);
+			}
+		} else {
+			rootNodes.push(node);
+		}
+	}
+
+	return { routes: rootNodes, errors };
+}
+
+/**
+ * Recursively finds all route files in a directory
+ */
+// biome-ignore lint/complexity/noExcessiveCognitiveComplexity: route file discovery branches
+function findRouteFiles(dir: string, prefix = ""): string[] {
+	const results: string[] = [];
+
+	const entries = readdirSync(dir, { withFileTypes: true });
+
+	for (const entry of entries) {
+		const relativePath = prefix ? `${prefix}/${entry.name}` : entry.name;
+
+		if (entry.isDirectory()) {
+			// Skip node_modules and hidden directories (except those in parentheses for groups)
+			if (entry.name === "node_modules" || (entry.name.startsWith(".") && !entry.name.startsWith("("))) {
+				continue;
+			}
+			results.push(...findRouteFiles(join(dir, entry.name), relativePath));
+		} else if (entry.isFile()) {
+			// Only include .ts and .tsx files
+			const ext = extname(entry.name);
+			if (ext !== ".ts" && ext !== ".tsx") {
+				continue;
+			}
+
+			// Skip test files
+			if (entry.name.includes(".test.") || entry.name.includes(".spec.")) {
+				continue;
+			}
+
+			// Skip hidden files (starting with _) except _layout
+			const baseName = basename(entry.name, ext);
+			if (baseName.startsWith("_") && baseName !== "_layout") {
+				continue;
+			}
+
+			results.push(relativePath);
+		}
+	}
+
+	return results;
+}
+
+/**
+ * Parses a route file and creates a RouteNode
+ */
+function parseRouteFile(relativePath: string, absolutePath: string): RouteNode | null {
+	const ext = extname(relativePath);
+	const fileName = basename(relativePath, ext);
+
+	const isLayout = fileName === "_layout";
+	const isIndex = fileName === "index";
+	const isCatchAll = fileName.startsWith("[...");
+
+	// Extract route group from path
+	const groupMatch = relativePath.match(/\(([^)]+)\)/);
+	const groupName = groupMatch ? groupMatch[1] : null;
+
+	// Parse params from the entire relative path (not just filename)
+	// This extracts params from both directory names and the filename
+	const params = extractParams(relativePath);
+
+	// Build URL path
+	const urlPath = buildUrlPath(relativePath, isIndex, isLayout);
+
+	return {
+		name: filePathToScreenName(relativePath),
+		path: urlPath,
+		filePath: absolutePath,
+		relativePath,
+		params,
+		children: [],
+		layoutType: isLayout ? detectLayoutType(absolutePath) : "none",
+		isIndex,
+		isLayout,
+		isCatchAll,
+		groupName,
+	};
+}
+
+/**
+ * Extracts dynamic parameters from a filename
+ */
+export function extractParams(fileName: string): ParamDefinition[] {
+	const params: ParamDefinition[] = [];
+	const regex = /\[(?:\.\.\.)?([^\]]+)\]\??/g;
+	let match: RegExpExecArray | null;
+
+	// biome-ignore lint/suspicious/noAssignInExpressions: standard regex iteration pattern
+	while ((match = regex.exec(fileName)) !== null) {
+		const fullMatch = match[0];
+		const paramName = match[1].replace("?", "");
+
+		params.push({
+			name: paramName,
+			isOptional: fullMatch.endsWith("?"),
+			isCatchAll: fullMatch.startsWith("[..."),
+		});
+	}
+
+	return params;
+}
+
+/**
+ * Builds a URL path from a relative file path
+ */
+export function buildUrlPath(relativePath: string, _isIndex: boolean, isLayout: boolean): string {
+	if (isLayout) return "";
+
+	const ext = extname(relativePath);
+	let urlPath = relativePath
+		.replace(ext, "") // Remove extension
+		.replace(/\\/g, "/") // Normalize path separators
+		.replace(/\(([^)]+)\)\//g, "") // Remove route groups from URL
+		.replace(/\[\.\.\.([^\]]+)\]/g, "*") // Catch-all
+		.replace(/\[([^\]]+)\]\?/g, ":$1?") // Optional params
+		.replace(/\[([^\]]+)\]/g, ":$1"); // Required params
+
+	// Handle index files - remove "index" or trailing "/index"
+	if (urlPath === "index") {
+		return "/";
+	}
+	urlPath = urlPath.replace(/\/index$/, "");
+
+	return `/${urlPath}` || "/";
+}
+
+/**
+ * Converts a file path to a screen name
+ */
+export function filePathToScreenName(relativePath: string): string {
+	const ext = extname(relativePath);
+	return relativePath.replace(ext, "").replace(/\\/g, "/");
+}
+
+/**
+ * Detects the layout type from a _layout.tsx file
+ */
+function detectLayoutType(absolutePath: string): "stack" | "tabs" | "drawer" {
+	try {
+		const content = readFileSync(absolutePath, "utf-8");
+
+		if (content.includes("type: 'tabs'") || content.includes('type: "tabs"')) {
+			return "tabs";
+		}
+		if (content.includes("type: 'drawer'") || content.includes('type: "drawer"')) {
+			return "drawer";
+		}
+	} catch {
+		// Default to stack on read error
+	}
+
+	return "stack";
+}
+
+/**
+ * Finds the parent layout file path for a given route file
+ */
+// biome-ignore lint/complexity/noExcessiveCognitiveComplexity: layout path traversal
+function findParentLayoutPath(filePath: string, routeNodes: Map<string, RouteNode>): string | null {
+	const dir = dirname(filePath);
+	const fileName = basename(filePath);
+	const isLayout = fileName === "_layout.tsx" || fileName === "_layout.ts";
+
+	// For root level files
+	if (dir === ".") {
+		// Check if there's a root _layout.tsx and this file is not the layout itself
+		const rootLayout = "_layout.tsx";
+		if (filePath !== rootLayout && routeNodes.has(rootLayout)) {
+			return rootLayout;
+		}
+		const rootLayoutTs = "_layout.ts";
+		if (filePath !== rootLayoutTs && routeNodes.has(rootLayoutTs)) {
+			return rootLayoutTs;
+		}
+		return null;
+	}
+
+	// For non-layout files, look for _layout in the same directory first
+	if (!isLayout) {
+		const sameDirLayout = `${dir}/_layout.tsx`;
+		const sameDirLayoutTs = `${dir}/_layout.ts`;
+
+		if (routeNodes.has(sameDirLayout)) {
+			return sameDirLayout;
+		}
+		if (routeNodes.has(sameDirLayoutTs)) {
+			return sameDirLayoutTs;
+		}
+	}
+
+	// For layouts, or if no layout in same directory, look in parent directories
+	let parentDir = dirname(dir);
+
+	while (parentDir !== ".") {
+		const layoutPath = `${parentDir}/_layout.tsx`;
+		const layoutPathTs = `${parentDir}/_layout.ts`;
+
+		if (routeNodes.has(layoutPath)) {
+			return layoutPath;
+		}
+		if (routeNodes.has(layoutPathTs)) {
+			return layoutPathTs;
+		}
+
+		parentDir = dirname(parentDir);
+	}
+
+	// Check root level layout
+	if (routeNodes.has("_layout.tsx") && filePath !== "_layout.tsx") {
+		return "_layout.tsx";
+	}
+	if (routeNodes.has("_layout.ts") && filePath !== "_layout.ts") {
+		return "_layout.ts";
+	}
+
+	return null;
+}
+
+/**
+ * Flattens a route tree into a flat array
+ */
+export function flattenRoutes(routes: RouteNode[]): RouteNode[] {
+	const result: RouteNode[] = [];
+
+	function traverse(nodes: RouteNode[]): void {
+		for (const node of nodes) {
+			result.push(node);
+			traverse(node.children);
+		}
+	}
+
+	traverse(routes);
+	return result;
+}

package/src/scanner/index.ts

@@ -0,0 +1,15 @@
+/**
+ * Scanner module for @teardown/navigation-metro
+ */
+
+export {
+	buildUrlPath,
+	extractParams,
+	filePathToScreenName,
+	flattenRoutes,
+	type ParamDefinition,
+	type RouteNode,
+	type ScanError,
+	type ScanResult,
+	scanRoutesDirectory,
+} from "./file-scanner";

package/src/validator/index.ts

@@ -0,0 +1,5 @@
+/**
+ * Validator module for @teardown/navigation-metro
+ */
+
+export { type ValidationError, validateRoutes } from "./route-validator";

package/src/validator/route-validator.test.ts

@@ -0,0 +1,192 @@
+import { afterEach, beforeEach, describe, expect, it } from "bun:test";
+import { mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { validateRoutes } from "./route-validator";
+
+const TEST_DIR = join(import.meta.dir, "__test_routes__");
+
+function createTestFile(relativePath: string, content: string) {
+	const fullPath = join(TEST_DIR, relativePath);
+	const dir = fullPath.substring(0, fullPath.lastIndexOf("/"));
+	mkdirSync(dir, { recursive: true });
+	writeFileSync(fullPath, content);
+}
+
+describe("Route Validator", () => {
+	beforeEach(() => {
+		mkdirSync(TEST_DIR, { recursive: true });
+	});
+
+	afterEach(() => {
+		rmSync(TEST_DIR, { recursive: true, force: true });
+	});
+
+	describe("validateRoutes", () => {
+		it("should return error for non-existent directory", () => {
+			const errors = validateRoutes("/non/existent/path");
+			expect(errors.length).toBeGreaterThan(0);
+			expect(errors[0].severity).toBe("error");
+		});
+
+		it("should return no errors for valid simple route", () => {
+			createTestFile(
+				"about.tsx",
+				`
+export default function About() {
+  return null;
+}
+      `
+			);
+
+			const errors = validateRoutes(TEST_DIR);
+			const actualErrors = errors.filter((e) => e.severity === "error");
+			expect(actualErrors).toEqual([]);
+		});
+
+		it("should detect missing default export", () => {
+			createTestFile(
+				"about.tsx",
+				`
+export function About() {
+  return null;
+}
+      `
+			);
+
+			const errors = validateRoutes(TEST_DIR);
+			const missingExport = errors.find((e) => e.message.includes("default export"));
+			expect(missingExport).toBeDefined();
+			expect(missingExport?.severity).toBe("error");
+		});
+
+		it("should detect duplicate route paths", () => {
+			// Create two routes that resolve to the same path
+			createTestFile("users/index.tsx", "export default function UsersIndex() {}");
+			// We can't easily create duplicate paths with file-based routing
+			// but we can simulate by checking the validator handles it
+			// For now, just check that the validator runs without error
+			const errors = validateRoutes(TEST_DIR);
+			expect(errors).toBeDefined();
+		});
+
+		it("should warn when screen doesn't use defineScreen", () => {
+			createTestFile(
+				"about.tsx",
+				`
+export default function About() {
+  return null;
+}
+      `
+			);
+
+			const errors = validateRoutes(TEST_DIR);
+			const warning = errors.find((e) => e.message.includes("defineScreen") && e.severity === "warning");
+			expect(warning).toBeDefined();
+		});
+
+		it("should not warn when screen uses defineScreen", () => {
+			createTestFile(
+				"about.tsx",
+				`
+import { defineScreen } from '@teardown/navigation';
+
+function AboutScreen() {
+  return null;
+}
+
+export default defineScreen({
+  component: AboutScreen,
+});
+      `
+			);
+
+			const errors = validateRoutes(TEST_DIR);
+			const defineScreenWarning = errors.find((e) => e.message.includes("defineScreen") && e.file.includes("about"));
+			expect(defineScreenWarning).toBeUndefined();
+		});
+
+		it("should warn when layout doesn't use defineLayout", () => {
+			createTestFile(
+				"_layout.tsx",
+				`
+export default {
+  type: 'stack'
+};
+      `
+			);
+
+			const errors = validateRoutes(TEST_DIR);
+			const warning = errors.find((e) => e.message.includes("defineLayout"));
+			expect(warning).toBeDefined();
+			expect(warning?.severity).toBe("warning");
+		});
+
+		it("should not warn when layout uses defineLayout", () => {
+			createTestFile(
+				"_layout.tsx",
+				`
+import { defineLayout } from '@teardown/navigation';
+
+export default defineLayout({
+  type: 'stack'
+});
+      `
+			);
+
+			const errors = validateRoutes(TEST_DIR);
+			const defineLayoutWarning = errors.find((e) => e.message.includes("defineLayout") && e.file.includes("_layout"));
+			expect(defineLayoutWarning).toBeUndefined();
+		});
+
+		it("should warn when dynamic route lacks param schema", () => {
+			createTestFile(
+				"users/[userId].tsx",
+				`
+export default function UserProfile() {
+  return null;
+}
+      `
+			);
+
+			const errors = validateRoutes(TEST_DIR);
+			const warning = errors.find((e) => e.message.includes("param") && e.message.includes("schema"));
+			expect(warning).toBeDefined();
+			expect(warning?.severity).toBe("warning");
+		});
+
+		it("should not warn when dynamic route has param schema", () => {
+			createTestFile(
+				"users/[userId].tsx",
+				`
+import { createParamSchema, paramValidators } from '@teardown/navigation';
+
+export const paramsSchema = createParamSchema({
+  userId: paramValidators.uuid(),
+});
+
+export default function UserProfile() {
+  return null;
+}
+      `
+			);
+
+			const errors = validateRoutes(TEST_DIR);
+			const schemaWarning = errors.find(
+				(e) => e.message.includes("param") && e.message.includes("schema") && e.file.includes("[userId]")
+			);
+			expect(schemaWarning).toBeUndefined();
+		});
+
+		it("should validate nested routes", () => {
+			createTestFile("_layout.tsx", "export default { type: 'stack' }");
+			createTestFile("users/_layout.tsx", "export default { type: 'stack' }");
+			createTestFile("users/index.tsx", "export default function Users() {}");
+			createTestFile("users/[userId].tsx", "export default function User() {}");
+
+			const errors = validateRoutes(TEST_DIR);
+			// Should have some warnings but no errors
+			const actualErrors = errors.filter((e) => e.severity === "error");
+			expect(actualErrors).toEqual([]);
+		});
+	});
+});