@sigil-dev/grimoire 0.7.6 → 0.7.7

package/src/typegen/index.ts

@@ -1,353 +1,356 @@
-import { mkdirSync, writeFileSync } from "node:fs";
-import { mkdir } from "node:fs/promises";
-import { dirname, isAbsolute, join, relative } from "node:path";
-import type { RouteFile, RouteTree } from "../routing/scanner.ts";
-
-export interface TypegenConfig {
-	projectRoot: string;
-	routesDir: string;
-	outDir: string; // absolute path to .grimoire/types
-}
-
-export interface RouteGroup {
-	dir: string;
-	paramNames: string[];
-	restParamNames: string[];
-	page?: RouteFile;
-	pageServer?: RouteFile;
-	layout?: RouteFile;
-	layoutServer?: RouteFile;
-	server?: RouteFile;
-	error?: RouteFile;
-}
-
-// On Windows, relative() returns the absolute `to` path when src and dest are on
-// different drives. Detect that and fall back to routes-dir-relative so join()
-// doesn't produce an invalid double-rooted path like "D:\out\C:\Users\...".
-function safeRelativeDir(
-	projectRoot: string,
-	routesDir: string,
-	groupDir: string,
-): string {
-	const rel = relative(projectRoot, groupDir);
-	return isAbsolute(rel) ? relative(routesDir, groupDir) : rel;
-}
-
-export function groupByDirectory(tree: RouteTree): Map<string, RouteGroup> {
-	const groups = new Map<string, RouteGroup>();
-
-	// Only process + convention files — simple files don't get $types
-	const files: RouteFile[] = [
-		...tree.routes.filter((f) => f.type !== "simple"),
-		...tree.layouts,
-		...tree.servers,
-		...tree.errors,
-	];
-
-	for (const file of files) {
-		const dir = dirname(file.filePath);
-		if (!groups.has(dir)) {
-			groups.set(dir, {
-				dir,
-				paramNames: file.paramNames,
-				restParamNames: file.restParamNames,
-			});
-		}
-		const g = groups.get(dir)!;
-		if (file.paramNames.length > g.paramNames.length) {
-			g.paramNames = file.paramNames;
-		}
-		if (file.restParamNames.length > g.restParamNames.length) {
-			g.restParamNames = file.restParamNames;
-		}
-		switch (file.type) {
-			case "page":
-				g.page = file;
-				break;
-			case "pageServer":
-				g.pageServer = file;
-				break;
-			case "layout":
-				g.layout = file;
-				break;
-			case "layoutServer":
-				g.layoutServer = file;
-				break;
-			case "server":
-				g.server = file;
-				break;
-			case "error":
-				g.error = file;
-				break;
-		}
-	}
-
-	return groups;
-}
-
-export function toImportPath(from: string, to: string): string {
-	return relative(from, to)
-		.replace(/\\/g, "/")
-		.replace(/\.tsx?$/, ".js");
-}
-
-export function buildParams(paramNames: string[], restParamNames: string[] = []): string {
-	const all = [...paramNames, ...restParamNames];
-	if (all.length === 0) return "{}";
-	const props = all.map((p) => `  ${p}: string;`).join("\n");
-	return `{\n${props}\n}`;
-}
-
-function generateTypesForGroup(group: RouteGroup, outFileDir: string): string {
-	const lines: string[] = [
-		"// Auto-generated by @sigil-dev/grimoire — do not edit",
-		"",
-	];
-
-	const paramsType = buildParams(group.paramNames, group.restParamNames);
-
-	// --- Params ---
-	lines.push(`export type Params = ${paramsType};`, "");
-
-	// --- PageData from +page.server.ts ---
-	if (group.pageServer) {
-		const imp = toImportPath(outFileDir, group.pageServer.filePath);
-		// Use `typeof import(...)` (not `import type * as NS`) so the module type
-		// can be used in `keyof` and indexed access without TS2709.
-		lines.push(
-			`type _PS = typeof import("${imp}");`,
-			`export type PageData = "load" extends keyof _PS`,
-			`  ? Awaited<ReturnType<_PS["load"]>>`,
-			`  : Record<string, never>;`,
-			"",
-		);
-		lines.push(
-			`export type PageProps = { data: PageData; params: Params };`,
-			"",
-		);
-		// PageServerLoad — annotate parameter, NOT return type, to preserve inference
-		lines.push(
-			`/** Annotate the load() parameter only — not the return type — or PageData loses its concrete keys. */`,
-			`export type PageServerLoad = (ctx: {`,
-			`  params: Params;`,
-			`  request: Request;`,
-			`  url: URL;`,
-			`  locals: App.Locals;`,
-			`}) => Record<string, unknown> | Promise<Record<string, unknown>>;`,
-			"",
-		);
-		// Actions — all exports except load and default
-		lines.push(
-			`type _ActionKeys = Exclude<keyof _PS, "load" | "default">;`,
-			`export type Actions = {`,
-			`  [K in _ActionKeys]: (ctx: {`,
-			`    params: Params;`,
-			`    request: Request;`,
-			`    url: URL;`,
-			`    locals: App.Locals;`,
-			`  }) => unknown | Promise<unknown>;`,
-			`};`,
-			"",
-		);
-	} else {
-		lines.push(
-			`export type PageData = Record<string, never>;`,
-			`export type PageProps = { data: PageData; params: Params };`,
-			`export type PageServerLoad = never;`,
-			`export type Actions = Record<string, never>;`,
-			"",
-		);
-	}
-
-	// --- LayoutData from +layout.server.ts ---
-	if (group.layoutServer) {
-		const imp = toImportPath(outFileDir, group.layoutServer.filePath);
-		lines.push(
-			`type _LS = typeof import("${imp}");`,
-			`export type LayoutData = "load" extends keyof _LS`,
-			`  ? Awaited<ReturnType<_LS["load"]>>`,
-			`  : Record<string, never>;`,
-			"",
-		);
-	} else {
-		lines.push(`export type LayoutData = Record<string, never>;`);
-	}
-
-	lines.push(
-		`export type LayoutProps = { data: LayoutData; params: Params; children?: unknown };`,
-		`export type LayoutServerLoad = (ctx: {`,
-		`  params: Params;`,
-		`  request: Request;`,
-		`  url: URL;`,
-		`  locals: App.Locals;`,
-		`}) => Record<string, unknown> | Promise<Record<string, unknown>>;`,
-		"",
-	);
-
-	// --- +server.ts API route handlers ---
-	if (group.server) {
-		const imp = toImportPath(outFileDir, group.server.filePath);
-		lines.push(
-			`type _SRV = typeof import("${imp}");`,
-			`type _HttpMethods = "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD" | "OPTIONS";`,
-			`type _ServerKeys = Extract<keyof _SRV, _HttpMethods>;`,
-			`export type ServerHandlers = {`,
-			`  [K in _ServerKeys]: (ctx: {`,
-			`    params: Params;`,
-			`    request: Request;`,
-			`    url: URL;`,
-			`    locals: App.Locals;`,
-			`  }) => Response | Promise<Response>;`,
-			`};`,
-			``,
-			`export type UpgradeContext = {`,
-			`  request: Request;`,
-			`  params: Params;`,
-			`  url: URL;`,
-			`  locals: App.Locals;`,
-			`};`,
-			``,
-			`type _UpgradeReturn = "upgrade" extends keyof _SRV`,
-			`  ? _SRV["upgrade"] extends (...args: any[]) => any`,
-			`    ? Awaited<ReturnType<_SRV["upgrade"]>>`,
-			`    : {}`,
-			`  : {};`,
-			`export type WsData = { params: Params } & Omit<_UpgradeReturn, "__handler">;`,
-			``,
-			`export type WebSocketHandler = {`,
-			`  open?(ws: ServerWebSocket<WsData>): void | Promise<void>;`,
-			`  message?(ws: ServerWebSocket<WsData>, data: string | Buffer): void | Promise<void>;`,
-			`  close?(ws: ServerWebSocket<WsData>, code: number, reason?: string): void | Promise<void>;`,
-			`  drain?(ws: ServerWebSocket<WsData>): void | Promise<void>;`,
-			`};`,
-			"",
-		);
-	}
-
-	// --- +error.tsx ---
-	if (group.error) {
-		lines.push(
-			`export type ErrorProps = { status: number; message: string };`,
-			"",
-		);
-	}
-
-	return lines.join("\n");
-}
-
-function generateAmbient(): string {
-	return [
-		"// Auto-generated by @sigil-dev/grimoire — do not edit",
-		"",
-		"declare namespace App {",
-		"  // Extend this interface in your app's src/app.d.ts to add typed locals",
-		"  interface Locals extends Record<string, unknown> {}",
-		"}",
-		"",
-		"// Available in all route files without import.",
-		"// Params default to Record<string,string>; for per-route typed params import from './$types'.",
-		"// Note: using these globals widens return types — PageData loses concrete keys.",
-		"// For precise data inference annotate load() with PageServerLoad from './$types'.",
-		"",
-		"type PageServerLoad<",
-		"  P extends Record<string, string> = Record<string, string>",
-		"> = (ctx: {",
-		"  params: P;",
-		"  request: Request;",
-		"  url: URL;",
-		"  locals: App.Locals;",
-		"}) => Record<string, unknown> | Promise<Record<string, unknown>>;",
-		"",
-		"type LayoutServerLoad<",
-		"  P extends Record<string, string> = Record<string, string>",
-		"> = (ctx: {",
-		"  params: P;",
-		"  request: Request;",
-		"  url: URL;",
-		"  locals: App.Locals;",
-		"}) => Record<string, unknown> | Promise<Record<string, unknown>>;",
-		"",
-		"type RequestHandler<",
-		"  P extends Record<string, string> = Record<string, string>",
-		"> = (ctx: {",
-		"  params: P;",
-		"  request: Request;",
-		"  url: URL;",
-		"  locals: App.Locals;",
-		"}) => Response | Promise<Response>;",
-		"",
-		"type PageProps<",
-		"  D extends Record<string, unknown> = Record<string, unknown>,",
-		"  P extends Record<string, string> = Record<string, string>",
-		"> = { data: D; params: P };",
-		"",
-		"type LayoutProps<",
-		"  D extends Record<string, unknown> = Record<string, unknown>,",
-		"  P extends Record<string, string> = Record<string, string>",
-		"> = { data: D; params: P; children?: unknown };",
-		"",
-		"type ErrorProps = { status: number; message: string };",
-		"",
-		"type UpgradeContext<",
-		"  P extends Record<string, string> = Record<string, string>",
-		"> = {",
-		"  params: P;",
-		"  request: Request;",
-		"  url: URL;",
-		"  locals: App.Locals;",
-		"};",
-		"",
-	].join("\n");
-}
-
-function generateTsConfig(): string {
-	return JSON.stringify(
-		{
-			compilerOptions: {
-				// Merges ".." (project root) and "./types" (.grimoire/types) into one
-				// virtual root so `import from './$types'` resolves without path aliases.
-				rootDirs: ["..", "./types"],
-			},
-			include: ["types/**/*.d.ts"],
-		},
-		null,
-		2,
-	);
-}
-
-export async function generateTypes(
-	tree: RouteTree,
-	config: TypegenConfig,
-): Promise<void> {
-	const { projectRoot, outDir } = config;
-
-	// Skip rm — on Windows, rm+mkdir in quick succession can race and leave dirs
-	// in an unusable state. Stale type files are harmless; we overwrite what we need.
-	await mkdir(outDir, { recursive: true }).catch(() => {});
-
-	const groups = groupByDirectory(tree);
-
-	for (const group of groups.values()) {
-		const routeRelDir = safeRelativeDir(
-			projectRoot,
-			config.routesDir,
-			group.dir,
-		);
-		const outFileDir = join(outDir, routeRelDir);
-		// Use mkdirSync — async mkdir on Windows/Bun can report success before
-		// the directory is actually visible to subsequent fs calls
-		mkdirSync(outFileDir, { recursive: true });
-
-		const content = generateTypesForGroup(group, outFileDir);
-		writeFileSync(join(outFileDir, "$types.d.ts"), content, "utf-8");
-	}
-
-	writeFileSync(join(outDir, "ambient.d.ts"), generateAmbient(), "utf-8");
-
-	const grimoireDir = dirname(outDir);
-	writeFileSync(
-		join(grimoireDir, "tsconfig.generated.json"),
-		generateTsConfig(),
-		"utf-8",
-	);
-}
+import { mkdirSync, writeFileSync } from "node:fs";
+import { mkdir } from "node:fs/promises";
+import { dirname, isAbsolute, join, relative } from "node:path";
+import type { RouteFile, RouteTree } from "../routing/scanner.ts";
+
+export interface TypegenConfig {
+	projectRoot: string;
+	routesDir: string;
+	outDir: string; // absolute path to .grimoire/types
+}
+
+export interface RouteGroup {
+	dir: string;
+	paramNames: string[];
+	restParamNames: string[];
+	page?: RouteFile;
+	pageServer?: RouteFile;
+	layout?: RouteFile;
+	layoutServer?: RouteFile;
+	server?: RouteFile;
+	error?: RouteFile;
+}
+
+// On Windows, relative() returns the absolute `to` path when src and dest are on
+// different drives. Detect that and fall back to routes-dir-relative so join()
+// doesn't produce an invalid double-rooted path like "D:\out\C:\Users\...".
+function safeRelativeDir(
+	projectRoot: string,
+	routesDir: string,
+	groupDir: string,
+): string {
+	const rel = relative(projectRoot, groupDir);
+	return isAbsolute(rel) ? relative(routesDir, groupDir) : rel;
+}
+
+export function groupByDirectory(tree: RouteTree): Map<string, RouteGroup> {
+	const groups = new Map<string, RouteGroup>();
+
+	// Only process + convention files — simple files don't get $types
+	const files: RouteFile[] = [
+		...tree.routes.filter((f) => f.type !== "simple"),
+		...tree.layouts,
+		...tree.servers,
+		...tree.errors,
+	];
+
+	for (const file of files) {
+		const dir = dirname(file.filePath);
+		if (!groups.has(dir)) {
+			groups.set(dir, {
+				dir,
+				paramNames: file.paramNames,
+				restParamNames: file.restParamNames,
+			});
+		}
+		const g = groups.get(dir)!;
+		if (file.paramNames.length > g.paramNames.length) {
+			g.paramNames = file.paramNames;
+		}
+		if (file.restParamNames.length > g.restParamNames.length) {
+			g.restParamNames = file.restParamNames;
+		}
+		switch (file.type) {
+			case "page":
+				g.page = file;
+				break;
+			case "pageServer":
+				g.pageServer = file;
+				break;
+			case "layout":
+				g.layout = file;
+				break;
+			case "layoutServer":
+				g.layoutServer = file;
+				break;
+			case "server":
+				g.server = file;
+				break;
+			case "error":
+				g.error = file;
+				break;
+		}
+	}
+
+	return groups;
+}
+
+export function toImportPath(from: string, to: string): string {
+	return relative(from, to)
+		.replace(/\\/g, "/")
+		.replace(/\.tsx?$/, ".js");
+}
+
+export function buildParams(
+	paramNames: string[],
+	restParamNames: string[] = [],
+): string {
+	const all = [...paramNames, ...restParamNames];
+	if (all.length === 0) return "{}";
+	const props = all.map((p) => `  ${p}: string;`).join("\n");
+	return `{\n${props}\n}`;
+}
+
+function generateTypesForGroup(group: RouteGroup, outFileDir: string): string {
+	const lines: string[] = [
+		"// Auto-generated by @sigil-dev/grimoire — do not edit",
+		"",
+	];
+
+	const paramsType = buildParams(group.paramNames, group.restParamNames);
+
+	// --- Params ---
+	lines.push(`export type Params = ${paramsType};`, "");
+
+	// --- PageData from +page.server.ts ---
+	if (group.pageServer) {
+		const imp = toImportPath(outFileDir, group.pageServer.filePath);
+		// Use `typeof import(...)` (not `import type * as NS`) so the module type
+		// can be used in `keyof` and indexed access without TS2709.
+		lines.push(
+			`type _PS = typeof import("${imp}");`,
+			`export type PageData = "load" extends keyof _PS`,
+			`  ? Awaited<ReturnType<_PS["load"]>>`,
+			`  : Record<string, never>;`,
+			"",
+		);
+		lines.push(
+			`export type PageProps = { data: PageData; params: Params };`,
+			"",
+		);
+		// PageServerLoad — annotate parameter, NOT return type, to preserve inference
+		lines.push(
+			`/** Annotate the load() parameter only — not the return type — or PageData loses its concrete keys. */`,
+			`export type PageServerLoad = (ctx: {`,
+			`  params: Params;`,
+			`  request: Request;`,
+			`  url: URL;`,
+			`  locals: App.Locals;`,
+			`}) => Record<string, unknown> | Promise<Record<string, unknown>>;`,
+			"",
+		);
+		// Actions — all exports except load and default
+		lines.push(
+			`type _ActionKeys = Exclude<keyof _PS, "load" | "default">;`,
+			`export type Actions = {`,
+			`  [K in _ActionKeys]: (ctx: {`,
+			`    params: Params;`,
+			`    request: Request;`,
+			`    url: URL;`,
+			`    locals: App.Locals;`,
+			`  }) => unknown | Promise<unknown>;`,
+			`};`,
+			"",
+		);
+	} else {
+		lines.push(
+			`export type PageData = Record<string, never>;`,
+			`export type PageProps = { data: PageData; params: Params };`,
+			`export type PageServerLoad = never;`,
+			`export type Actions = Record<string, never>;`,
+			"",
+		);
+	}
+
+	// --- LayoutData from +layout.server.ts ---
+	if (group.layoutServer) {
+		const imp = toImportPath(outFileDir, group.layoutServer.filePath);
+		lines.push(
+			`type _LS = typeof import("${imp}");`,
+			`export type LayoutData = "load" extends keyof _LS`,
+			`  ? Awaited<ReturnType<_LS["load"]>>`,
+			`  : Record<string, never>;`,
+			"",
+		);
+	} else {
+		lines.push(`export type LayoutData = Record<string, never>;`);
+	}
+
+	lines.push(
+		`export type LayoutProps = { data: LayoutData; params: Params; children?: unknown };`,
+		`export type LayoutServerLoad = (ctx: {`,
+		`  params: Params;`,
+		`  request: Request;`,
+		`  url: URL;`,
+		`  locals: App.Locals;`,
+		`}) => Record<string, unknown> | Promise<Record<string, unknown>>;`,
+		"",
+	);
+
+	// --- +server.ts API route handlers ---
+	if (group.server) {
+		const imp = toImportPath(outFileDir, group.server.filePath);
+		lines.push(
+			`type _SRV = typeof import("${imp}");`,
+			`type _HttpMethods = "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD" | "OPTIONS";`,
+			`type _ServerKeys = Extract<keyof _SRV, _HttpMethods>;`,
+			`export type ServerHandlers = {`,
+			`  [K in _ServerKeys]: (ctx: {`,
+			`    params: Params;`,
+			`    request: Request;`,
+			`    url: URL;`,
+			`    locals: App.Locals;`,
+			`  }) => Response | Promise<Response>;`,
+			`};`,
+			``,
+			`export type UpgradeContext = {`,
+			`  request: Request;`,
+			`  params: Params;`,
+			`  url: URL;`,
+			`  locals: App.Locals;`,
+			`};`,
+			``,
+			`type _UpgradeReturn = "upgrade" extends keyof _SRV`,
+			`  ? _SRV["upgrade"] extends (...args: any[]) => any`,
+			`    ? Awaited<ReturnType<_SRV["upgrade"]>>`,
+			`    : {}`,
+			`  : {};`,
+			`export type WsData = { params: Params } & Omit<_UpgradeReturn, "__handler">;`,
+			``,
+			`export type WebSocketHandler = {`,
+			`  open?(ws: ServerWebSocket<WsData>): void | Promise<void>;`,
+			`  message?(ws: ServerWebSocket<WsData>, data: string | Buffer): void | Promise<void>;`,
+			`  close?(ws: ServerWebSocket<WsData>, code: number, reason?: string): void | Promise<void>;`,
+			`  drain?(ws: ServerWebSocket<WsData>): void | Promise<void>;`,
+			`};`,
+			"",
+		);
+	}
+
+	// --- +error.tsx ---
+	if (group.error) {
+		lines.push(
+			`export type ErrorProps = { status: number; message: string; error: unknown; route: string };`,
+			"",
+		);
+	}
+
+	return lines.join("\n");
+}
+
+function generateAmbient(): string {
+	return [
+		"// Auto-generated by @sigil-dev/grimoire — do not edit",
+		"",
+		"declare namespace App {",
+		"  // Extend this interface in your app's src/app.d.ts to add typed locals",
+		"  interface Locals extends Record<string, unknown> {}",
+		"}",
+		"",
+		"// Available in all route files without import.",
+		"// Params default to Record<string,string>; for per-route typed params import from './$types'.",
+		"// Note: using these globals widens return types — PageData loses concrete keys.",
+		"// For precise data inference annotate load() with PageServerLoad from './$types'.",
+		"",
+		"type PageServerLoad<",
+		"  P extends Record<string, string> = Record<string, string>",
+		"> = (ctx: {",
+		"  params: P;",
+		"  request: Request;",
+		"  url: URL;",
+		"  locals: App.Locals;",
+		"}) => Record<string, unknown> | Promise<Record<string, unknown>>;",
+		"",
+		"type LayoutServerLoad<",
+		"  P extends Record<string, string> = Record<string, string>",
+		"> = (ctx: {",
+		"  params: P;",
+		"  request: Request;",
+		"  url: URL;",
+		"  locals: App.Locals;",
+		"}) => Record<string, unknown> | Promise<Record<string, unknown>>;",
+		"",
+		"type RequestHandler<",
+		"  P extends Record<string, string> = Record<string, string>",
+		"> = (ctx: {",
+		"  params: P;",
+		"  request: Request;",
+		"  url: URL;",
+		"  locals: App.Locals;",
+		"}) => Response | Promise<Response>;",
+		"",
+		"type PageProps<",
+		"  D extends Record<string, unknown> = Record<string, unknown>,",
+		"  P extends Record<string, string> = Record<string, string>",
+		"> = { data: D; params: P };",
+		"",
+		"type LayoutProps<",
+		"  D extends Record<string, unknown> = Record<string, unknown>,",
+		"  P extends Record<string, string> = Record<string, string>",
+		"> = { data: D; params: P; children?: unknown };",
+		"",
+		"type ErrorProps = { status: number; message: string; error: unknown; route: string };",
+		"",
+		"type UpgradeContext<",
+		"  P extends Record<string, string> = Record<string, string>",
+		"> = {",
+		"  params: P;",
+		"  request: Request;",
+		"  url: URL;",
+		"  locals: App.Locals;",
+		"};",
+		"",
+	].join("\n");
+}
+
+function generateTsConfig(): string {
+	return JSON.stringify(
+		{
+			compilerOptions: {
+				// Merges ".." (project root) and "./types" (.grimoire/types) into one
+				// virtual root so `import from './$types'` resolves without path aliases.
+				rootDirs: ["..", "./types"],
+			},
+			include: ["types/**/*.d.ts"],
+		},
+		null,
+		2,
+	);
+}
+
+export async function generateTypes(
+	tree: RouteTree,
+	config: TypegenConfig,
+): Promise<void> {
+	const { projectRoot, outDir } = config;
+
+	// Skip rm — on Windows, rm+mkdir in quick succession can race and leave dirs
+	// in an unusable state. Stale type files are harmless; we overwrite what we need.
+	await mkdir(outDir, { recursive: true }).catch(() => {});
+
+	const groups = groupByDirectory(tree);
+
+	for (const group of groups.values()) {
+		const routeRelDir = safeRelativeDir(
+			projectRoot,
+			config.routesDir,
+			group.dir,
+		);
+		const outFileDir = join(outDir, routeRelDir);
+		// Use mkdirSync — async mkdir on Windows/Bun can report success before
+		// the directory is actually visible to subsequent fs calls
+		mkdirSync(outFileDir, { recursive: true });
+
+		const content = generateTypesForGroup(group, outFileDir);
+		writeFileSync(join(outFileDir, "$types.d.ts"), content, "utf-8");
+	}
+
+	writeFileSync(join(outDir, "ambient.d.ts"), generateAmbient(), "utf-8");
+
+	const grimoireDir = dirname(outDir);
+	writeFileSync(
+		join(grimoireDir, "tsconfig.generated.json"),
+		generateTsConfig(),
+		"utf-8",
+	);
+}