@buzola/vite-plugin 0.0.1

package/src/generator/codegen.ts

@@ -0,0 +1,214 @@
+import * as path from 'node:path'
+import type { FileRouteNode } from './tree-builder'
+
+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[]
+}
+
+/**
+ * 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/vite-plugin. Do not edit.')
+	lines.push('/* eslint-disable */')
+	lines.push('')
+
+	// Framework imports first — needed by lazy component declarations below
+	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('')
+
+	// Collect route imports — importsByKey maps "filePath::exportName" → import info
+	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++)
+
+	// Generate route imports
+	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('')
+
+	// Collect page info for type augmentation and registry
+	const pages = collectPages(tree)
+
+	// Generate page map type augmentation
+	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'
+				return p.optional ? `${p.name}?: ${type}` : `${p.name}: ${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(`    ${param}: true;`)
+		}
+		lines.push('  }')
+	}
+	lines.push('}')
+	lines.push('')
+
+	// Generate page registry
+	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('')
+
+	// Generate route tree config
+	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[], parentPath = ''): 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, node.fullPath))
+		}
+	}
+
+	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)
+				const importPath = relativePath.startsWith('.') ? relativePath : `./${relativePath}`
+				// Strip extension for import
+				const cleanPath = importPath.replace(/\.(tsx?|jsx?)$/, '')
+				const varName = `Route${nextId()}`
+				const isLazy = !node.isLayout // Layouts are eagerly loaded, pages are lazy
+				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}` : '/'}',`)
+
+		if (imp) {
+			if (imp.isLazy) {
+				lines.push(`${pad}  component: lazy(${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}},`)
+	}
+}
+
+/**
+ * Generate the virtual module content for `virtual:buzola/routes`.
+ */
+export function generateVirtualModule(outputPath: string): string {
+	return `export { routes, pageRegistry } from '${outputPath.replace(/\.ts$/, '')}';\n`
+}

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'
+
+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
+}

package/src/generator/tree-builder.ts

@@ -0,0 +1,354 @@
+import * as path from 'node:path'
+import { parseDirName, parseFileName } from '../conventions'
+import type { ExtractedPage, ModuleLoader } from './page-extractor'
+import { extractPages } from './page-extractor'
+import type { ScannedFile } from './scanner'
+
+/**
+ * Page export info attached to a file route node.
+ */
+export interface PageExportInfo {
+	/** Page ID (e.g., "project/detail"). */
+	pageId: string
+	/** Export name (e.g., "default", "detail"). */
+	exportName: string
+	/** Route pattern (e.g., "/project/:id"). */
+	routePattern: string
+	/** Param info extracted from the page schema. */
+	params: { name: string; optional: boolean; array: boolean }[]
+}
+
+/**
+ * A node in the file-based route tree (before compilation into RouteNode).
+ */
+export interface FileRouteNode {
+	/** Route path segment (from file name, or derived from .route() pattern). */
+	segment: string
+	/** Full path from root. */
+	fullPath: string
+	/** Absolute file path to the component. */
+	filePath?: string
+	/** Which export to use from the file ("default" or a named export). */
+	exportName?: string
+	/** Whether this is a layout. */
+	isLayout: boolean
+	/** Whether this is an index route. */
+	isIndex: boolean
+	/** Whether this is a not-found catch-all. */
+	isNotFound: boolean
+	/** Whether this is a pathless group. */
+	isPathlessGroup: boolean
+	/** Page exports discovered in this file. */
+	pageExports?: PageExportInfo[]
+	/** Children nodes. */
+	children: FileRouteNode[]
+}
+
+/**
+ * Build a route tree from scanned files.
+ * Loads each module via moduleLoader to extract createPage() metadata.
+ */
+export async function buildFileRouteTree(files: ScannedFile[], moduleLoader: ModuleLoader): Promise<FileRouteNode[]> {
+	const root: FileRouteNode = {
+		segment: '',
+		fullPath: '/',
+		isLayout: false,
+		isIndex: false,
+		isNotFound: false,
+		isPathlessGroup: false,
+		children: [],
+	}
+
+	for (const file of files) {
+		await insertFile(root, file, moduleLoader)
+	}
+
+	sortChildren(root)
+
+	if (root.isLayout && root.filePath) {
+		return [root]
+	}
+
+	return root.children
+}
+
+async function insertFile(root: FileRouteNode, file: ScannedFile, moduleLoader: ModuleLoader): Promise<void> {
+	const ext = path.extname(file.relativePath)
+	const withoutExt = file.relativePath.slice(0, -ext.length)
+	const parts = withoutExt.split(path.sep)
+	const fileName = parts.pop()!
+	const dirs = parts
+
+	let current = root
+	let currentPath = ''
+
+	for (const dir of dirs) {
+		const dirInfo = parseDirName(dir)
+		const segmentPath = dirInfo.isPathlessGroup
+			? currentPath
+			: joinPath(currentPath, dirInfo.segment)
+
+		let child = current.children.find(c => c.segment === dirInfo.segment && c.isPathlessGroup === dirInfo.isPathlessGroup && c.isLayout)
+
+		if (!child) {
+			child = current.children.find(c => c.segment === dirInfo.segment && c.isPathlessGroup === dirInfo.isPathlessGroup && !c.filePath)
+		}
+
+		if (!child) {
+			child = {
+				segment: dirInfo.segment,
+				fullPath: segmentPath || '/',
+				isLayout: false,
+				isIndex: false,
+				isNotFound: false,
+				isPathlessGroup: dirInfo.isPathlessGroup,
+				children: [],
+			}
+			current.children.push(child)
+		}
+
+		current = child
+		currentPath = segmentPath
+	}
+
+	const fileInfo = parseFileName(fileName)
+
+	if (fileInfo.isLayout) {
+		current.isLayout = true
+		current.filePath = file.absolutePath
+	} else if (fileInfo.isNotFound) {
+		const catchAllSegment = ':__notFound+'
+		const fullPath = joinPath(currentPath, catchAllSegment)
+		const pageId = dirs.length === 0 ? '404' : `${dirs.join('/')}/404`
+		const pageExports: PageExportInfo[] = [{
+			pageId,
+			exportName: 'default',
+			routePattern: fullPath,
+			params: [{ name: '__notFound', optional: false, array: false }],
+		}]
+		const notFoundNode: FileRouteNode = {
+			segment: catchAllSegment,
+			fullPath,
+			filePath: file.absolutePath,
+			isLayout: false,
+			isIndex: false,
+			isNotFound: true,
+			isPathlessGroup: false,
+			pageExports,
+			children: [],
+		}
+		current.children.push(notFoundNode)
+	} else if (fileInfo.isIndex) {
+		const fullPath = currentPath || '/'
+		const allExports = await extractPageExportsFromFile(file, dirs, '', true, currentPath, moduleLoader)
+		const defaultExports = allExports?.filter(e => e.exportName === 'default')
+		const namedExports = allExports?.filter(e => e.exportName !== 'default') ?? []
+
+		const hasDefault = defaultExports != null && defaultExports.length > 0
+		const indexNode: FileRouteNode = {
+			segment: '',
+			fullPath,
+			filePath: hasDefault ? file.absolutePath : undefined,
+			exportName: hasDefault ? 'default' : undefined,
+			isLayout: false,
+			isIndex: true,
+			isNotFound: false,
+			isPathlessGroup: false,
+			pageExports: hasDefault ? defaultExports : undefined,
+			children: [],
+		}
+		current.children.push(indexNode)
+
+		// Named exports become siblings (children of current, not of the index node)
+		for (const exp of namedExports) {
+			const namedSegment = exp.routePattern ? (computeRelativeSegment(currentPath, exp.routePattern) ?? exp.exportName) : exp.exportName
+			checkCollision(current.children, namedSegment, file.absolutePath, exp.exportName)
+			current.children.push({
+				segment: namedSegment,
+				fullPath: joinPath(currentPath, namedSegment),
+				filePath: file.absolutePath,
+				exportName: exp.exportName,
+				isLayout: false,
+				isIndex: false,
+				isNotFound: false,
+				isPathlessGroup: false,
+				pageExports: [exp],
+				children: [],
+			})
+		}
+	} else {
+		const allExports = await extractPageExportsFromFile(file, dirs, fileName, false, currentPath, moduleLoader)
+		const defaultExports = allExports?.filter(e => e.exportName === 'default')
+		const namedExports = allExports?.filter(e => e.exportName !== 'default') ?? []
+
+		const hasDefault = defaultExports != null && defaultExports.length > 0
+		const routeSegment = hasDefault ? deriveSegmentFromPageExports(defaultExports, currentPath) : undefined
+		const segment = routeSegment ?? fileInfo.segment
+		const fullPath = joinPath(currentPath, segment)
+
+		if (hasDefault) {
+			checkCollision(current.children, segment, file.absolutePath, 'default')
+		}
+
+		// Reuse existing container node (created by a previous file's named exports) if available
+		let routeNode = !hasDefault ? current.children.find(c => c.segment === segment && !c.filePath && !c.isLayout && !c.isPathlessGroup) : undefined
+		if (!routeNode) {
+			routeNode = {
+				segment,
+				fullPath,
+				filePath: hasDefault ? file.absolutePath : undefined,
+				exportName: hasDefault ? 'default' : undefined,
+				isLayout: false,
+				isIndex: false,
+				isNotFound: false,
+				isPathlessGroup: false,
+				pageExports: hasDefault ? defaultExports : undefined,
+				children: [],
+			}
+			current.children.push(routeNode)
+		}
+
+		// Named exports become children (equivalent to files in a subdirectory)
+		for (const exp of namedExports) {
+			const namedSegment = exp.routePattern ? (computeRelativeSegment(fullPath, exp.routePattern) ?? exp.exportName) : exp.exportName
+			checkCollision(routeNode.children, namedSegment, file.absolutePath, exp.exportName)
+			routeNode.children.push({
+				segment: namedSegment,
+				fullPath: joinPath(fullPath, namedSegment),
+				filePath: file.absolutePath,
+				exportName: exp.exportName,
+				isLayout: false,
+				isIndex: false,
+				isNotFound: false,
+				isPathlessGroup: false,
+				pageExports: [exp],
+				children: [],
+			})
+		}
+	}
+}
+
+/**
+ * Derive page ID from file path and export name.
+ *
+ * Examples:
+ * - File: project.tsx, export: detail → "project/detail"
+ * - File: project.tsx, export: default → "project"
+ * - File: project/detail.tsx, export: default → "project/detail"
+ * - File: index.tsx, export: default → "index"
+ */
+function derivePageId(dirs: string[], fileName: string, isIndex: boolean, exportName: string): string {
+	const segments = [...dirs]
+
+	if (isIndex) {
+		if (segments.length === 0) {
+			return exportName === 'default' ? 'index' : `index/${exportName}`
+		}
+		const base = segments.join('/')
+		return exportName === 'default' ? base : `${base}/${exportName}`
+	}
+
+	segments.push(fileName)
+	const base = segments.join('/')
+
+	return exportName === 'default' ? base : `${base}/${exportName}`
+}
+
+/**
+ * Compute the relative route segment from a page's .route() pattern and parent path.
+ */
+function computeRelativeSegment(parentPath: string, routePattern: string): string | undefined {
+	const prefix = parentPath === '/' ? '/' : parentPath + '/'
+
+	if (routePattern.startsWith(prefix)) {
+		return routePattern.slice(prefix.length)
+	}
+
+	if (routePattern === parentPath) {
+		return undefined
+	}
+
+	const lastSlash = routePattern.lastIndexOf('/')
+	return lastSlash >= 0 ? routePattern.slice(lastSlash + 1) : routePattern
+}
+
+function deriveSegmentFromPageExports(
+	pageExports: PageExportInfo[] | undefined,
+	parentPath: string,
+): string | undefined {
+	if (!pageExports || pageExports.length === 0) return undefined
+	const firstRoute = pageExports[0].routePattern
+	return computeRelativeSegment(parentPath, firstRoute)
+}
+
+async function extractPageExportsFromFile(
+	file: ScannedFile,
+	dirs: string[],
+	fileName: string,
+	isIndex: boolean,
+	parentPath: string,
+	moduleLoader: ModuleLoader,
+): Promise<PageExportInfo[] | undefined> {
+	let pages: ExtractedPage[]
+	try {
+		pages = await extractPages(file.absolutePath, moduleLoader)
+	} catch {
+		return undefined
+	}
+
+	if (pages.length === 0) return undefined
+
+	const result: PageExportInfo[] = []
+
+	for (const page of pages) {
+		const pageId = derivePageId(dirs, fileName, isIndex, page.exportName)
+		// If no explicit .route(), derive from file path — all params become query params
+		const basePath = isIndex ? (parentPath || '/') : joinPath(parentPath, fileName)
+		const routePattern = page.route ?? (page.isDefault ? basePath : joinPath(basePath, page.exportName))
+
+		result.push({
+			pageId,
+			exportName: page.exportName,
+			routePattern,
+			params: page.params,
+		})
+	}
+
+	return result.length > 0 ? result : undefined
+}
+
+function checkCollision(siblings: FileRouteNode[], segment: string, filePath: string, exportName: string): void {
+	const existing = siblings.find(c => c.segment === segment && !c.isLayout && !c.isPathlessGroup)
+	if (!existing || !existing.filePath) return
+
+	const existingDesc = existing.exportName && existing.exportName !== 'default'
+		? `named export '${existing.exportName}' in '${existing.filePath}'`
+		: `'${existing.filePath}'`
+	const newDesc = exportName !== 'default'
+		? `named export '${exportName}' in '${filePath}'`
+		: `'${filePath}'`
+
+	throw new Error(`Route collision: ${newDesc} conflicts with ${existingDesc} — both resolve to segment '${segment}'`)
+}
+
+function sortChildren(node: FileRouteNode): void {
+	for (const child of node.children) {
+		sortChildren(child)
+	}
+
+	node.children.sort((a, b) => sortWeight(a) - sortWeight(b))
+}
+
+function sortWeight(node: FileRouteNode): number {
+	if (node.isIndex) return 0
+	if (node.isNotFound) return 4
+	if (node.segment.includes(':') && node.segment.includes('+')) return 3
+	if (node.segment.includes(':')) return 2
+	return 1
+}
+
+function joinPath(parent: string, child: string): string {
+	if (!child) return parent || '/'
+	const base = parent || ''
+	return `${base}/${child}`
+}

package/src/index.ts

@@ -0,0 +1,17 @@
+export { buzolaPlugin } from './plugin'
+export type { BuzolaPluginOptions } from './plugin'
+
+export { scanRouteFiles } from './generator/scanner'
+export type { ScannedFile } from './generator/scanner'
+
+export { buildFileRouteTree } from './generator/tree-builder'
+export type { FileRouteNode, PageExportInfo } from './generator/tree-builder'
+
+export { generateRouteModule } from './generator/codegen'
+export type { CodegenOptions } from './generator/codegen'
+
+export { extractPages } from './generator/page-extractor'
+export type { ExtractedPage, ExtractedParam, ModuleLoader } from './generator/page-extractor'
+
+export { isRouteFile, parseDirName, parseFileName, parseRouteFile } from './conventions'
+export type { ParsedRouteFile } from './conventions'