@buzola/codegen 0.0.1

package/src/generator/tree-builder.ts

@@ -0,0 +1,449 @@
+import * as path from 'node:path'
+import { parseDirName, parseFileName } from '../conventions.js'
+import type { ExtractedPage, ModuleLoader } from './page-extractor.js'
+import { extractPages } from './page-extractor.js'
+import type { ScannedFile } from './scanner.js'
+
+/**
+ * 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 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[]
+}
+
+// ─── Flat route entry (intermediate representation) ─────────────────────────
+
+interface RouteEntry {
+	routePattern: string
+	/** File-hierarchy-based position for tree building (may differ from routePattern when .route() is used). */
+	treePosition: string
+	filePath: string
+	exportName: string
+	kind: 'page' | 'layout' | 'notFound'
+	pageId?: string
+	params: { name: string; optional: boolean; array: boolean }[]
+	/** File-system-derived URL path (ignoring pathless groups). */
+	fileScope: string
+	/** Chain of pathless group directory paths this file is nested under. */
+	pathlessGroups: string[]
+	/** For pathless group layouts: the directory path of the group. */
+	pathlessGroupId?: string
+}
+
+// ─── Public API ─────────────────────────────────────────────────────────────
+
+/**
+ * Build a route tree from scanned files.
+ * Loads each module via moduleLoader to extract createPage() metadata.
+ *
+ * Two-phase approach:
+ * 1. Extract flat route entries from all files.
+ * 2. Build the tree using route-pattern prefix matching (not file hierarchy).
+ */
+export async function buildFileRouteTree(files: ScannedFile[], moduleLoader: ModuleLoader): Promise<FileRouteNode[]> {
+	const entries = await extractEntries(files, moduleLoader)
+	return buildTreeFromEntries(entries)
+}
+
+// ─── Phase 1: Extract flat route entries ────────────────────────────────────
+
+async function extractEntries(files: ScannedFile[], moduleLoader: ModuleLoader): Promise<RouteEntry[]> {
+	const perFile = await Promise.all(files.map(file => extractFileEntries(file, moduleLoader)))
+	return perFile.flat()
+}
+
+async function extractFileEntries(file: ScannedFile, moduleLoader: ModuleLoader): Promise<RouteEntry[]> {
+	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
+	const fileInfo = parseFileName(fileName)
+
+	let fileScope = ''
+	const pathlessGroups: string[] = []
+	let groupPath = ''
+
+	for (const dir of dirs) {
+		groupPath = groupPath ? `${groupPath}/${dir}` : dir
+		const dirInfo = parseDirName(dir)
+		if (dirInfo.isPathlessGroup) {
+			pathlessGroups.push(groupPath)
+		} else {
+			fileScope = joinPath(fileScope, dirInfo.segment)
+		}
+	}
+	if (!fileScope) fileScope = '/'
+
+	if (fileInfo.isLayout) {
+		const lastDir = dirs.length > 0 ? dirs[dirs.length - 1] : null
+		const isPathlessGroupLayout = lastDir != null && parseDirName(lastDir).isPathlessGroup
+
+		return [{
+			routePattern: fileScope,
+			treePosition: fileScope,
+			filePath: file.absolutePath,
+			exportName: 'default',
+			kind: 'layout',
+			params: [],
+			fileScope,
+			pathlessGroups,
+			pathlessGroupId: isPathlessGroupLayout ? groupPath : undefined,
+		}]
+	}
+
+	if (fileInfo.isNotFound) {
+		const catchAllPattern = fileScope === '/' ? '/:__notFound+' : `${fileScope}/:__notFound+`
+		const pageId = dirs.length === 0 ? '404' : `${dirs.join('/')}/404`
+		return [{
+			routePattern: catchAllPattern,
+			treePosition: catchAllPattern,
+			filePath: file.absolutePath,
+			exportName: 'default',
+			kind: 'notFound',
+			pageId,
+			params: [{ name: '__notFound', optional: false, array: false }],
+			fileScope,
+			pathlessGroups,
+		}]
+	}
+
+	const isIndex = fileInfo.isIndex
+	const basePath = isIndex ? fileScope : joinPath(fileScope, fileName)
+	const pages = await safeExtractPages(file, moduleLoader)
+
+	if (pages.length === 0) {
+		return [{
+			routePattern: basePath,
+			treePosition: basePath,
+			filePath: file.absolutePath,
+			exportName: 'default',
+			kind: 'page',
+			params: [],
+			fileScope,
+			pathlessGroups,
+		}]
+	}
+
+	return pages.map(page => {
+		const pageId = derivePageId(dirs, fileName, isIndex, page.exportName)
+		const defaultPattern = page.isDefault ? basePath : joinPath(basePath, page.exportName)
+		return {
+			routePattern: page.route ?? defaultPattern,
+			treePosition: defaultPattern,
+			filePath: file.absolutePath,
+			exportName: page.exportName,
+			kind: 'page',
+			pageId,
+			params: page.params,
+			fileScope,
+			pathlessGroups,
+		}
+	})
+}
+
+// ─── Phase 2: Build tree from flat entries ──────────────────────────────────
+
+interface LayoutRef {
+	node: FileRouteNode
+	pathlessGroupId?: string
+}
+
+function buildTreeFromEntries(entries: RouteEntry[]): FileRouteNode[] {
+	const root: FileRouteNode = {
+		segment: '',
+		fullPath: '/',
+		isLayout: false,
+		isIndex: false,
+		isNotFound: false,
+		isPathlessGroup: false,
+		children: [],
+	}
+
+	const layouts = entries.filter(e => e.kind === 'layout')
+	const pages = entries.filter(e => e.kind !== 'layout')
+
+	// Sort layouts: shorter routePattern first, non-pathless before pathless
+	layouts.sort((a, b) => {
+		if (a.routePattern.length !== b.routePattern.length) return a.routePattern.length - b.routePattern.length
+		if (a.pathlessGroupId && !b.pathlessGroupId) return 1
+		if (!a.pathlessGroupId && b.pathlessGroupId) return -1
+		return 0
+	})
+
+	// Insert layouts into tree
+	// Track all layout nodes for page assignment
+	const layoutRefs: LayoutRef[] = [{ node: root }]
+
+	for (const layout of layouts) {
+		if (layout.pathlessGroupId) {
+			// Pathless group layout — find parent by walking layoutRefs, respecting pathless group chain
+			const parent = findParentForPathlessGroupLayout(layoutRefs, layout)
+			const node: FileRouteNode = {
+				segment: '',
+				fullPath: layout.treePosition,
+				filePath: layout.filePath,
+				isLayout: true,
+				isIndex: false,
+				isNotFound: false,
+				isPathlessGroup: true,
+				children: [],
+			}
+			parent.node.children.push(node)
+			layoutRefs.push({ node, pathlessGroupId: layout.pathlessGroupId })
+		} else if (layout.treePosition === '/' && !root.filePath) {
+			// Root layout
+			root.isLayout = true
+			root.filePath = layout.filePath
+		} else if (layout.treePosition === '/') {
+			// Additional layout at root (shouldn't happen normally, but handle)
+			root.isLayout = true
+			root.filePath = layout.filePath
+		} else {
+			// Regular layout — find parent by prefix matching
+			const parent = findDeepestLayoutParent(layoutRefs, layout.treePosition, layout.pathlessGroups)
+			const segment = computeSegmentFromParent(parent.node.fullPath, layout.treePosition)
+			const node: FileRouteNode = {
+				segment,
+				fullPath: layout.treePosition,
+				filePath: layout.filePath,
+				isLayout: true,
+				isIndex: false,
+				isNotFound: false,
+				isPathlessGroup: false,
+				children: [],
+			}
+			parent.node.children.push(node)
+			layoutRefs.push({ node })
+		}
+	}
+
+	// Insert pages into tree (using file-hierarchy position, not route pattern)
+	for (const entry of pages) {
+		const parent = findDeepestLayoutParent(layoutRefs, entry.treePosition, entry.pathlessGroups)
+		const isIndex = entry.treePosition === parent.node.fullPath
+		const segment = isIndex ? '' : computeSegmentFromParent(parent.node.fullPath, entry.treePosition)
+
+		const pageExports: PageExportInfo[] | undefined = entry.pageId
+			? [{
+				pageId: entry.pageId,
+				exportName: entry.exportName,
+				routePattern: entry.routePattern,
+				params: entry.params,
+			}]
+			: undefined
+
+		// For named exports from the same file as an existing node, check collision
+		if (!isIndex) {
+			checkCollision(parent.node.children, segment, entry.filePath, entry.exportName)
+		}
+
+		// Try to reuse an existing container node (e.g., from a directory that has no _layout.tsx)
+		const existing = !isIndex
+			? parent.node.children.find(c => c.segment === segment && !c.filePath && !c.isLayout && !c.isPathlessGroup)
+			: undefined
+
+		if (existing) {
+			existing.filePath = entry.filePath
+			existing.exportName = entry.exportName
+			existing.pageExports = pageExports
+		} else {
+			parent.node.children.push({
+				segment,
+				fullPath: entry.treePosition,
+				filePath: entry.filePath,
+				exportName: entry.exportName,
+				isLayout: false,
+				isIndex,
+				isNotFound: entry.kind === 'notFound',
+				isPathlessGroup: false,
+				pageExports,
+				children: [],
+			})
+		}
+	}
+
+	// Sort children recursively
+	sortChildren(root)
+
+	if (root.isLayout && root.filePath) {
+		return [root]
+	}
+
+	return root.children
+}
+
+/**
+ * Find the parent layout for a pathless group layout.
+ * The parent is the deepest layout at the same routePattern level,
+ * considering the pathless group nesting chain.
+ */
+function findParentForPathlessGroupLayout(layoutRefs: LayoutRef[], entry: RouteEntry): LayoutRef {
+	// The parent is the layout whose pathlessGroupId is the previous entry in the chain,
+	// or the deepest non-pathless layout at the same routePattern if this is the first group.
+	const groupChain = entry.pathlessGroups
+	const thisGroupIndex = groupChain.indexOf(entry.pathlessGroupId!)
+
+	if (thisGroupIndex > 0) {
+		// Has a parent pathless group — find it
+		const parentGroupId = groupChain[thisGroupIndex - 1]
+		const parentRef = layoutRefs.find(r => r.pathlessGroupId === parentGroupId)
+		if (parentRef) return parentRef
+	}
+
+	// First pathless group in chain (or parent not found) — find the deepest regular layout at prefix
+	let best = layoutRefs[0] // root
+	for (const ref of layoutRefs) {
+		if (ref.pathlessGroupId) continue // skip other pathless groups
+		if (isPathPrefixOrEqual(ref.node.fullPath, entry.routePattern) && ref.node.fullPath.length >= best.node.fullPath.length) {
+			best = ref
+		}
+	}
+	return best
+}
+
+/**
+ * Find the deepest layout whose routePattern is a prefix of the given pattern.
+ * Respects pathless group membership.
+ */
+function findDeepestLayoutParent(layoutRefs: LayoutRef[], routePattern: string, pathlessGroups: string[]): LayoutRef {
+	let best = layoutRefs[0] // root
+
+	for (const ref of layoutRefs) {
+		if (!isPathPrefixOrEqual(ref.node.fullPath, routePattern)) continue
+
+		// For pathless groups, only match if the entry belongs to this group
+		if (ref.pathlessGroupId && !pathlessGroups.includes(ref.pathlessGroupId)) continue
+
+		// Prefer deeper matches. For ties (pathless groups at same depth), prefer pathless group
+		// that the entry belongs to over non-pathless.
+		if (ref.node.fullPath.length > best.node.fullPath.length) {
+			best = ref
+		} else if (ref.node.fullPath.length === best.node.fullPath.length && ref.pathlessGroupId && pathlessGroups.includes(ref.pathlessGroupId)) {
+			best = ref
+		}
+	}
+
+	return best
+}
+
+function isPathPrefixOrEqual(prefix: string, path: string): boolean {
+	if (prefix === '/') return true
+	return path === prefix || path.startsWith(prefix + '/')
+}
+
+function computeSegmentFromParent(parentFullPath: string, childFullPath: string): string {
+	if (parentFullPath === '/') return childFullPath.slice(1)
+	return childFullPath.slice(parentFullPath.length + 1)
+}
+
+// ─── Helpers ────────────────────────────────────────────────────────────────
+
+/**
+ * Derive page ID from file path and export name.
+ */
+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}`
+}
+
+async function safeExtractPages(file: ScannedFile, moduleLoader: ModuleLoader): Promise<ExtractedPage[]> {
+	try {
+		return await extractPages(file.absolutePath, moduleLoader)
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error)
+		const stack = error instanceof Error && error.stack ? `\n${error.stack}` : ''
+		console.warn(
+			`[buzola] Failed to extract page metadata from "${file.relativePath}". `
+				+ `The file will be treated as a plain component (no typed params, no loader, no custom route). `
+				+ `Cause: ${message}${stack}`,
+		)
+		return []
+	}
+}
+
+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))
+}
+
+const SORT_INDEX = 0
+const SORT_STATIC = 1
+const SORT_DYNAMIC = 2
+const SORT_CATCHALL = 3
+const SORT_NOT_FOUND = 4
+
+function sortWeight(node: FileRouteNode): number {
+	if (node.isIndex) return SORT_INDEX
+	if (node.isNotFound) return SORT_NOT_FOUND
+	if (node.segment.includes(':') && node.segment.includes('+')) return SORT_CATCHALL
+	if (node.segment.includes(':')) return SORT_DYNAMIC
+	return SORT_STATIC
+}
+
+function joinPath(parent: string, child: string): string {
+	if (!child) return parent || '/'
+	if (!parent || parent === '/') return `/${child}`
+	return `${parent}/${child}`
+}

package/src/index.ts

@@ -0,0 +1,23 @@
+export { generate } from './generate.js'
+export type { GenerateOptions } from './generate.js'
+
+export { loadConfig } from './config.js'
+export type { BuzolaConfig } from './config.js'
+
+export { buildVirtualSource, BUZOLA_NAMESPACE, resolveOptions, resolveVirtualModuleId, VIRTUAL_ID_PATTERN, VIRTUAL_PREFIX } from './resolve.js'
+export type { BasePluginOptions, ResolvedOptions, ResolveOptionsInput, VirtualModuleId } from './resolve.js'
+
+export { scanRouteFiles } from './generator/scanner.js'
+export type { ScannedFile } from './generator/scanner.js'
+
+export { buildFileRouteTree } from './generator/tree-builder.js'
+export type { FileRouteNode, PageExportInfo } from './generator/tree-builder.js'
+
+export { generateRouteModule } from './generator/codegen.js'
+export type { CodegenOptions } from './generator/codegen.js'
+
+export { extractPages } from './generator/page-extractor.js'
+export type { ExtractedPage, ExtractedParam, ModuleLoader } from './generator/page-extractor.js'
+
+export { isRouteFile, parseDirName, parseFileName, parseRouteFile } from './conventions.js'
+export type { ParsedRouteFile } from './conventions.js'

package/src/resolve.ts

@@ -0,0 +1,75 @@
+import * as path from 'node:path'
+import type { BuzolaConfig } from './config.js'
+import { loadConfig } from './config.js'
+import type { GenerateOptions } from './generate.js'
+
+export interface ResolveOptionsInput extends BuzolaConfig {
+	/** Project root used to resolve relative paths and locate `buzola.config.*`. Defaults to `process.cwd()`. */
+	root?: string
+}
+
+/** Shared base for bundler-plugin option types. */
+export interface BasePluginOptions extends ResolveOptionsInput {
+	/**
+	 * Unique name for this plugin instance. Required when registering multiple
+	 * entrypoints in the same bundler config. Affects the plugin name
+	 * (`buzola:${name}`) and the virtual module ID (`virtual:buzola/${name}/routes`).
+	 *
+	 * When omitted, the plugin uses `buzola` as its name and
+	 * `virtual:buzola/routes` as the virtual module ID.
+	 */
+	name?: string
+}
+
+export interface ResolvedOptions extends GenerateOptions {
+	root: string
+}
+
+/**
+ * Resolve plugin/CLI input against `buzola.config.*` and built-in defaults.
+ * Returns absolute paths plus the resolved project root.
+ */
+export async function resolveOptions(input: ResolveOptionsInput = {}): Promise<ResolvedOptions> {
+	const root = path.resolve(input.root ?? process.cwd())
+	const fileConfig = await loadConfig(root)
+	return {
+		root,
+		routesDir: path.resolve(root, input.routesDir ?? fileConfig.routesDir ?? 'src/routes'),
+		outputPath: path.resolve(root, input.output ?? fileConfig.output ?? 'src/buzola.gen.ts'),
+		persistentParams: input.persistentParams ?? fileConfig.persistentParams,
+	}
+}
+
+/** Namespace owned by every Buzola plugin instance. */
+export const BUZOLA_NAMESPACE = 'buzola'
+/** Prefix shared by every Buzola virtual module ID. */
+export const VIRTUAL_PREFIX = 'virtual:buzola/'
+/** Regex matching every Buzola virtual module ID, suitable for bundler `filter` options. */
+export const VIRTUAL_ID_PATTERN = /^virtual:buzola\//
+
+export interface VirtualModuleId {
+	/** Plugin name (e.g. `buzola` or `buzola:admin`). */
+	pluginName: string
+	/** Virtual module ID (e.g. `virtual:buzola/routes` or `virtual:buzola/admin/routes`). */
+	id: string
+}
+
+/**
+ * Derive plugin name and virtual module ID. `name` distinguishes multiple
+ * entrypoints in the same bundler config.
+ */
+export function resolveVirtualModuleId(name: string | undefined): VirtualModuleId {
+	return {
+		pluginName: name ? `${BUZOLA_NAMESPACE}:${name}` : BUZOLA_NAMESPACE,
+		id: name ? `${VIRTUAL_PREFIX}${name}/routes` : `${VIRTUAL_PREFIX}routes`,
+	}
+}
+
+/**
+ * Build the virtual module source — re-exports `routes` and `pageRegistry`
+ * from the generated file at `outputPath`.
+ */
+export function buildVirtualSource(outputPath: string): string {
+	const importPath = outputPath.replace(/\.ts$/, '')
+	return `export { routes, pageRegistry } from ${JSON.stringify(importPath)};\n`
+}