@buzola/codegen 0.0.1

package/src/conventions.ts

@@ -0,0 +1,116 @@
+import * as path from 'node:path'
+
+/**
+ * File naming conventions for page-centric routing.
+ *
+ * _layout.tsx   → Layout wrapper (renders children via <Outlet />)
+ * _404.tsx      → Not-found catch-all (auto-assigned catch-all pattern within parent scope)
+ * index.tsx     → Index route (renders at parent's exact path)
+ * about.tsx     → Named page file (page ID derived from file name)
+ * (group)/      → Pathless group (no URL segment)
+ *
+ * Files prefixed with `_` are special convention files, not regular pages.
+ * Route patterns (URL paths) come exclusively from `.route()` on `createPage()`.
+ * File names only determine page IDs and layout nesting.
+ */
+
+export const ROUTE_FILE_EXTENSIONS = ['.tsx', '.jsx', '.ts', '.js']
+
+export interface ParsedRouteFile {
+	/** The route segment this file contributes. */
+	segment: string
+	/** Whether this is a layout file. */
+	isLayout: boolean
+	/** Whether this is an index file. */
+	isIndex: boolean
+	/** Whether this is a not-found catch-all file. */
+	isNotFound: boolean
+	/** Whether this directory is a pathless group. */
+	isPathlessGroup: boolean
+	/** Original file path relative to routes dir. */
+	relativePath: string
+}
+
+/**
+ * Check if a file is a route file based on extension.
+ */
+export function isRouteFile(filePath: string): boolean {
+	return ROUTE_FILE_EXTENSIONS.some(ext => filePath.endsWith(ext))
+}
+
+/**
+ * Parse a directory name for routing conventions.
+ */
+export function parseDirName(name: string): { segment: string; isPathlessGroup: boolean } {
+	// Pathless group: (auth)
+	if (name.startsWith('(') && name.endsWith(')')) {
+		return { segment: '', isPathlessGroup: true }
+	}
+
+	return { segment: name, isPathlessGroup: false }
+}
+
+/**
+ * Parse a route file name (without extension) into routing info.
+ */
+export function parseFileName(nameWithoutExt: string): {
+	segment: string
+	isLayout: boolean
+	isIndex: boolean
+	isNotFound: boolean
+} {
+	if (nameWithoutExt === '_layout') {
+		return { segment: '', isLayout: true, isIndex: false, isNotFound: false }
+	}
+
+	if (nameWithoutExt === '_404') {
+		return { segment: '', isLayout: false, isIndex: false, isNotFound: true }
+	}
+
+	if (nameWithoutExt === 'index') {
+		return { segment: '', isLayout: false, isIndex: true, isNotFound: false }
+	}
+
+	return { segment: nameWithoutExt, isLayout: false, isIndex: false, isNotFound: false }
+}
+
+/**
+ * Parse a route file path relative to the routes directory.
+ */
+export function parseRouteFile(relativePath: string): ParsedRouteFile {
+	const ext = path.extname(relativePath)
+	const withoutExt = relativePath.slice(0, -ext.length)
+	const parts = withoutExt.split(path.sep)
+	const fileName = parts.pop()!
+	const dirs = parts
+
+	const fileInfo = parseFileName(fileName)
+
+	// Build segment from directory path + file
+	const segments: string[] = []
+	let isPathlessGroup = false
+
+	for (const dir of dirs) {
+		const dirInfo = parseDirName(dir)
+		if (dirInfo.isPathlessGroup) {
+			isPathlessGroup = true
+		} else {
+			segments.push(dirInfo.segment)
+		}
+	}
+
+	if (fileInfo.segment) {
+		segments.push(fileInfo.segment)
+	}
+
+	const segment = segments.length > 0 ? segments.join('/') : ''
+
+	return {
+		segment,
+		isLayout: fileInfo.isLayout,
+		isIndex: fileInfo.isIndex,
+		isNotFound: fileInfo.isNotFound,
+		isPathlessGroup,
+		relativePath,
+	}
+}

package/src/generate.ts

@@ -0,0 +1,67 @@
+import * as fs from 'node:fs'
+import { generateRouteModule } from './generator/codegen.js'
+import type { ModuleLoader } from './generator/page-extractor.js'
+import { scanRouteFiles } from './generator/scanner.js'
+import { buildFileRouteTree } from './generator/tree-builder.js'
+
+export interface GenerateOptions {
+	/** Absolute path to the routes directory. */
+	routesDir: string
+	/** Absolute path to the output file. */
+	outputPath: string
+	/** Parameter names that should be persistent across navigations. */
+	persistentParams?: string[]
+	/** Custom module loader. Defaults to native `import()`. */
+	moduleLoader?: ModuleLoader
+	/** When true, return `false` instead of throwing if `routesDir` is missing. */
+	optional?: boolean
+}
+
+/**
+ * Generate the `buzola.gen.ts` route module from a routes directory.
+ *
+ * Works standalone (no Vite required) — uses native `import()` as the
+ * default module loader. Pass a custom `moduleLoader` to integrate with
+ * Vite's `ssrLoadModule` or other bundlers.
+ *
+ * Note: The default module loader uses native `import()`, which can load
+ * `.ts`/`.tsx` files with Bun but not with Node.js. For Node.js, provide
+ * a custom `moduleLoader` (e.g. via Vite's `ssrLoadModule`).
+ *
+ * @returns `true` if the output file was written (content changed), `false` otherwise.
+ */
+export async function generate(options: GenerateOptions): Promise<boolean> {
+	const { routesDir, outputPath, persistentParams, moduleLoader = defaultModuleLoader, optional = false } = options
+
+	if (!fs.existsSync(routesDir)) {
+		if (optional) return false
+		throw new Error(`Routes directory does not exist: ${routesDir}`)
+	}
+
+	const files = scanRouteFiles(routesDir)
+	const tree = await buildFileRouteTree(files, moduleLoader)
+	const code = generateRouteModule({ tree, routesDir, outputPath, persistentParams })
+
+	return writeIfChanged(outputPath, code)
+}
+
+async function defaultModuleLoader(absolutePath: string): Promise<Record<string, unknown>> {
+	try {
+		return await import(absolutePath)
+	} catch (error) {
+		throw new Error(
+			`Failed to load module "${absolutePath}". The default module loader uses native import() which `
+				+ `supports .ts/.tsx files with Bun but not Node.js. For Node.js, provide a custom moduleLoader option.`,
+			{ cause: error },
+		)
+	}
+}
+
+function writeIfChanged(filePath: string, content: string): boolean {
+	if (fs.existsSync(filePath) && fs.readFileSync(filePath, 'utf-8') === content) {
+		return false
+	}
+
+	fs.writeFileSync(filePath, content, 'utf-8')
+	return true
+}

package/src/generator/codegen.ts

@@ -0,0 +1,213 @@
+import * as path from 'node:path'
+import type { FileRouteNode } from './tree-builder.js'
+
+export interface CodegenOptions {
+	/** The route tree from file scanning. */
+	tree: FileRouteNode[]
+	/** Absolute path to the routes directory. */
+	routesDir: string
+	/** Absolute path to the output file. */
+	outputPath: string
+	/** Parameter names that should be persistent across navigations. */
+	persistentParams?: string[]
+}
+
+/**
+ * Quote a property key when it isn't a valid JS identifier (e.g. hyphenated).
+ */
+function formatPropertyKey(name: string): string {
+	return /^[A-Za-z_$][\w$]*$/.test(name) ? name : `'${name}'`
+}
+
+/**
+ * Generate the buzola.gen.ts file with:
+ * 1. Module augmentation for BuzolaPageMap (type safety)
+ * 2. Page registry (page ID → route pattern)
+ * 3. Route tree construction code
+ */
+export function generateRouteModule(options: CodegenOptions): string {
+	const { tree, outputPath } = options
+	const outputDir = path.dirname(outputPath)
+	let importCounter = 0
+
+	const lines: string[] = []
+
+	lines.push('// This file is auto-generated by @buzola/codegen. Do not edit.')
+	lines.push('/* eslint-disable */')
+	lines.push('')
+
+	lines.push(`import { lazy, type ComponentType } from 'react';`)
+	lines.push(`import { buildRouteTree } from '@buzola/router';`)
+	lines.push(`import type { RouteConfig } from '@buzola/router';`)
+	lines.push('')
+
+	const imports: { varName: string; filePath: string; isLazy: boolean; exportName: string }[] = []
+	const importsByKey = new Map<string, { varName: string; isLazy: boolean }>()
+	collectImports(tree, outputDir, imports, importsByKey, () => importCounter++)
+
+	for (const imp of imports) {
+		if (imp.isLazy) {
+			lines.push(
+				`const ${imp.varName} = () => import('${imp.filePath}').then(m => ({ default: m.${imp.exportName}.component })) as Promise<{ default: ComponentType }>;`,
+			)
+		} else {
+			if (imp.exportName !== 'default') {
+				lines.push(`import { ${imp.exportName} as ${imp.varName} } from '${imp.filePath}';`)
+			} else {
+				lines.push(`import ${imp.varName} from '${imp.filePath}';`)
+			}
+		}
+	}
+
+	lines.push('')
+
+	const pages = collectPages(tree)
+
+	lines.push('// Module augmentation for type-safe page-centric routing')
+	lines.push(`declare module '@buzola/router' {`)
+	lines.push('  interface BuzolaPageMap {')
+	for (const page of pages) {
+		if (page.params.length === 0) {
+			lines.push(`    '${page.pageId}': {};`)
+		} else {
+			const paramEntries = page.params.map(p => {
+				const type = p.array ? 'string[]' : 'string'
+				const key = formatPropertyKey(p.name)
+				return p.optional ? `${key}?: ${type}` : `${key}: ${type}`
+			}).join('; ')
+			lines.push(`    '${page.pageId}': { ${paramEntries} };`)
+		}
+	}
+	lines.push('  }')
+	if (options.persistentParams && options.persistentParams.length > 0) {
+		lines.push('  interface BuzolaPersistentParams {')
+		for (const param of options.persistentParams) {
+			lines.push(`    ${formatPropertyKey(param)}: true;`)
+		}
+		lines.push('  }')
+	}
+	lines.push('}')
+	lines.push('')
+
+	lines.push('// Page registry — page ID → route pattern')
+	lines.push('export const pageRegistry: Record<string, string> = {')
+	for (const page of pages) {
+		lines.push(`  '${page.pageId}': '${page.routePattern}',`)
+	}
+	lines.push('};')
+	lines.push('')
+
+	lines.push('const routeConfigs: RouteConfig[] = [')
+	generateTreeConfig(tree, lines, importsByKey, 1)
+	lines.push('];')
+	lines.push('')
+	lines.push('export const routes = buildRouteTree(routeConfigs);')
+	lines.push('')
+
+	return lines.join('\n')
+}
+
+interface PageInfo {
+	pageId: string
+	routePattern: string
+	params: { name: string; optional: boolean; array: boolean }[]
+}
+
+/**
+ * Collect page info from the file route tree for codegen.
+ */
+function collectPages(nodes: FileRouteNode[]): PageInfo[] {
+	const result: PageInfo[] = []
+
+	for (const node of nodes) {
+		if (node.filePath && !node.isLayout && !node.isNotFound) {
+			if (node.pageExports) {
+				for (const exp of node.pageExports) {
+					result.push({
+						pageId: exp.pageId,
+						routePattern: exp.routePattern,
+						params: exp.params,
+					})
+				}
+			}
+		}
+
+		if (node.children.length > 0) {
+			result.push(...collectPages(node.children))
+		}
+	}
+
+	return result
+}
+
+function importKey(filePath: string, exportName?: string): string {
+	return `${filePath}::${exportName ?? 'default'}`
+}
+
+function collectImports(
+	nodes: FileRouteNode[],
+	outputDir: string,
+	imports: { varName: string; filePath: string; isLazy: boolean; exportName: string }[],
+	importsByKey: Map<string, { varName: string; isLazy: boolean }>,
+	nextId: () => number,
+): void {
+	for (const node of nodes) {
+		if (node.filePath) {
+			const key = importKey(node.filePath, node.exportName)
+			if (!importsByKey.has(key)) {
+				const relativePath = path.relative(outputDir, node.filePath).replaceAll('\\', '/')
+				const importPath = relativePath.startsWith('.') ? relativePath : `./${relativePath}`
+				const cleanPath = importPath.replace(/\.(tsx?|jsx?)$/, '')
+				const varName = `Route${nextId()}`
+				const isLazy = !node.isLayout
+				const exportName = node.exportName ?? 'default'
+				imports.push({ varName, filePath: cleanPath, isLazy, exportName })
+				importsByKey.set(key, { varName, isLazy })
+			}
+		}
+
+		collectImports(node.children, outputDir, imports, importsByKey, nextId)
+	}
+}
+
+function generateTreeConfig(
+	nodes: FileRouteNode[],
+	lines: string[],
+	importsByKey: Map<string, { varName: string; isLazy: boolean }>,
+	indent: number,
+): void {
+	const pad = '  '.repeat(indent)
+
+	for (const node of nodes) {
+		const imp = node.filePath ? importsByKey.get(importKey(node.filePath, node.exportName)) : undefined
+
+		lines.push(`${pad}{`)
+		lines.push(`${pad}  path: '${node.segment ? `/${node.segment}` : '/'}',`)
+
+		// Emit matchPath when page has a custom route pattern that differs from file-hierarchy position
+		if (node.pageExports && node.pageExports.length > 0 && node.pageExports[0].routePattern !== node.fullPath) {
+			lines.push(`${pad}  matchPath: '${node.pageExports[0].routePattern}',`)
+		}
+
+		if (imp) {
+			if (imp.isLazy) {
+				lines.push(`${pad}  component: lazy(${imp.varName}),`)
+				lines.push(`${pad}  preload: ${imp.varName},`)
+			} else {
+				lines.push(`${pad}  component: ${imp.varName},`)
+			}
+		}
+
+		if (node.isLayout) lines.push(`${pad}  isLayout: true,`)
+		if (node.isIndex) lines.push(`${pad}  isIndex: true,`)
+		if (node.isPathlessGroup) lines.push(`${pad}  isPathlessGroup: true,`)
+
+		if (node.children.length > 0) {
+			lines.push(`${pad}  children: [`)
+			generateTreeConfig(node.children, lines, importsByKey, indent + 2)
+			lines.push(`${pad}  ],`)
+		}
+
+		lines.push(`${pad}},`)
+	}
+}

package/src/generator/page-extractor.ts

@@ -0,0 +1,48 @@
+export interface ExtractedPage {
+	/** Export name (e.g., "detail", "list"). "default" for default exports. */
+	exportName: string
+	/** Explicit route pattern from .route('...'), if present. */
+	route?: string
+	/** Whether this is a default export. */
+	isDefault: boolean
+	/** Extracted param info from .params(z.object({...})). */
+	params: ExtractedParam[]
+}
+
+export interface ExtractedParam {
+	name: string
+	optional: boolean
+	array: boolean
+}
+
+export type ModuleLoader = (absolutePath: string) => Promise<Record<string, unknown>>
+
+function isPageDefinition(value: unknown): value is {
+	__buzolaPage: true
+	route?: string
+	paramsMeta: { name: string; optional: boolean; array: boolean }[]
+} {
+	return value != null && typeof value === 'object' && '__buzolaPage' in value && (value as any).__buzolaPage === true
+}
+
+/**
+ * Extract createPage() metadata by loading the module and inspecting exports.
+ */
+export async function extractPages(absolutePath: string, loadModule: ModuleLoader): Promise<ExtractedPage[]> {
+	const mod = await loadModule(absolutePath)
+	const pages: ExtractedPage[] = []
+
+	for (const [key, value] of Object.entries(mod)) {
+		if (!isPageDefinition(value)) continue
+
+		const exportName = key === 'default' ? 'default' : key
+		pages.push({
+			exportName,
+			isDefault: key === 'default',
+			route: value.route,
+			params: value.paramsMeta ?? [],
+		})
+	}
+
+	return pages
+}

package/src/generator/scanner.ts

@@ -0,0 +1,45 @@
+import * as fs from 'node:fs'
+import * as path from 'node:path'
+import { isRouteFile } from '../conventions.js'
+
+export interface ScannedFile {
+	/** Absolute path to the file. */
+	absolutePath: string
+	/** Path relative to the routes directory. */
+	relativePath: string
+}
+
+/**
+ * Scan a directory recursively for route files.
+ */
+export function scanRouteFiles(routesDir: string): ScannedFile[] {
+	const files: ScannedFile[] = []
+
+	function scan(dir: string): void {
+		if (!fs.existsSync(dir)) return
+
+		const entries = fs.readdirSync(dir, { withFileTypes: true })
+
+		for (const entry of entries) {
+			const fullPath = path.join(dir, entry.name)
+
+			if (entry.isDirectory()) {
+				// Skip node_modules and hidden directories
+				if (entry.name.startsWith('.') || entry.name === 'node_modules') continue
+				scan(fullPath)
+			} else if (entry.isFile() && isRouteFile(entry.name)) {
+				files.push({
+					absolutePath: fullPath,
+					relativePath: path.relative(routesDir, fullPath),
+				})
+			}
+		}
+	}
+
+	scan(routesDir)
+
+	// Sort for deterministic output
+	files.sort((a, b) => a.relativePath.localeCompare(b.relativePath))
+
+	return files
+}