@vigla/kit 0.0.0-stage → 0.1.0

package/src/sync/app-types.ts

@@ -0,0 +1,164 @@
+import { join } from 'node:path';
+import type { EnvVarConfig } from '../types/env.ts';
+import type { ValidatedConfig } from '../types/builder.ts';
+import type { PageOptions, RouteParam, RouteTree } from '../types/internal/routes.ts';
+import { parseRoute, resolveRoute, routeSegments } from '../shared/routing/index.ts';
+import { importPath, writeChanged } from './files.ts';
+
+interface ParameterVariants {
+	optional: boolean;
+	matchers: Set<string> | null;
+}
+
+export function parameterType(
+	params: readonly RouteParam[],
+	directory: string,
+	root: string,
+	matcherFile: string | null,
+	name: string
+): string {
+	const grouped = new Map<string, ParameterVariants>();
+	for (const param of params) {
+		const prior = grouped.get(param.name);
+		if (!prior)
+			grouped.set(param.name, {
+				optional: param.optional,
+				matchers: param.matcher ? new Set([param.matcher]) : null
+			});
+		else {
+			prior.optional &&= param.optional;
+			if (!param.matcher) prior.matchers = null;
+			else prior.matchers?.add(param.matcher);
+		}
+	}
+	return `{ ${[...grouped]
+		.map(([key, param]) => {
+			const type =
+				param.matchers && matcherFile
+					? [...param.matchers]
+							.map(
+								(matcher) =>
+									`import(${JSON.stringify(name + '/params')}).MatcherParam<(typeof import(${JSON.stringify(importPath(directory, join(root, matcherFile)))}).params)[${JSON.stringify(matcher)}]>`
+							)
+							.join(' | ')
+					: 'string';
+			return `${JSON.stringify(key)}${param.optional ? '?' : ''}: ${type}${param.optional ? ' | undefined' : ''}`;
+		})
+		.join('; ')} }`;
+}
+
+function pathnameTypes(id: string): string[] {
+	let paths = [''];
+	for (const segment of routeSegments(id)) {
+		const params = parseRoute('/' + segment).params;
+		const values = Object.fromEntries(params.map((param) => [param.name, '${string}']));
+		const path = resolveRoute('/' + segment, values).slice(1);
+		const omittable =
+			params.length === 1 && params[0]!.chained && (params[0]!.optional || params[0]!.rest);
+		paths = paths.flatMap((prefix) => {
+			const joined = prefix ? prefix + '/' + path : path;
+			return omittable ? [joined, prefix] : [joined];
+		});
+	}
+	return [...new Set(paths)];
+}
+function pathType(path: string): string {
+	return path.includes('${string}')
+		? '`' + path.replaceAll('`', '\\`').replace(/\$\{(?!string\})/g, '\\${') + '` & {}'
+		: JSON.stringify(path);
+}
+function withSlash(path: string, options: PageOptions | null): string[] {
+	if (path === '') return [''];
+	if (options === null || options.trailingSlash === 'ignore') return [path, path + '/'];
+	return [options.trailingSlash === 'always' ? path + '/' : path];
+}
+
+export function writeAppTypes(
+	config: ValidatedConfig,
+	tree: RouteTree,
+	root: string,
+	name: string
+): void {
+	const directory = join(root, 'node_modules/$app/types');
+	const pages = tree.routes.filter((route) => route.page);
+	const endpoints = tree.routes.filter((route) => route.endpoint);
+	const routes = tree.routes.filter((route) => route.page || route.endpoint);
+	const union = (ids: string[]): string =>
+		ids.map((id) => JSON.stringify(id)).join(' | ') || 'never';
+	const params = routes
+		.filter((route) => route.params.length)
+		.map(
+			(route) =>
+				`${JSON.stringify(route.id)}: ${parameterType(route.params, directory, root, tree.params, name)}`
+		);
+	const layouts = tree.routes
+		.filter((route) => route.layout !== null)
+		.map((route) => {
+			const found = [...route.params];
+			for (const child of tree.routes.filter((child) =>
+				child.id.startsWith(route.id === '/' ? '/' : route.id + '/')
+			)) {
+				found.push(...child.params.map((param) => ({ ...param, optional: true })));
+			}
+			return `${JSON.stringify(route.id)}: ${parameterType(found, directory, root, tree.params, name)}`;
+		});
+	const paths = new Set<string>();
+	for (const route of routes) {
+		const options: Array<PageOptions | null> = [];
+		if (route.page) options.push(tree.nodes[route.page.leaf]!.options);
+		if (route.endpoint) options.push(route.endpoint.options);
+		for (const path of pathnameTypes(route.id))
+			for (const option of options)
+				for (const variant of withSlash(path, option)) paths.add(pathType(variant));
+	}
+	const content = [
+		`import ${JSON.stringify(name)};`,
+		'declare module "$app/types" {',
+		'\texport interface AppTypes {',
+		`\t\tPageRouteId(): ${union(pages.map(({ id }) => id))};`,
+		`\t\tEndpointRouteId(): ${union(endpoints.map(({ id }) => id))};`,
+		`\t\tRouteId(): ${union(routes.map(({ id }) => id))};`,
+		`\t\tRouteParams(): { ${params.join('; ')} };`,
+		`\t\tLayoutParams(): { ${layouts.join('; ')} };`,
+		`\t\tPath(): ${[...paths].join(' | ') || 'never'};`,
+		`\t\tResolvedPathname(): \`\${${JSON.stringify(config.paths.base + '/')}}\${ReturnType<AppTypes["Path"]>}\`${config.paths.relative ? ' | `${"." | ".." | `../${string}`}/${ReturnType<AppTypes["Path"]>}`' : ''};`,
+		`\t\tAssetPath(): ${union(tree.assets.map(({ file }) => file))};`,
+		'\t}',
+		'}'
+	].join('\n');
+	writeChanged(join(directory, 'non-ambient.d.ts'), content);
+	writeChanged(
+		join(directory, 'index.d.ts'),
+		`import ${JSON.stringify(name)};\nimport './env.js';\nimport './non-ambient.js';\n`
+	);
+}
+
+export function writeEnvironment(
+	root: string,
+	name: string,
+	entry: string | null,
+	variables: Record<string, EnvVarConfig<any>> | null
+): void {
+	const directory = join(root, 'node_modules/$app/types');
+	const source = entry ? importPath(directory, entry) : '';
+	const content = ['private', 'public']
+		.map((visibility) => {
+			const declarations = Object.entries(variables ?? {})
+				.filter(([, config]) => !!config.public === (visibility === 'public'))
+				.map(([key, config]) => {
+					const type =
+						config.schema && entry
+							? `Value<typeof import(${JSON.stringify(source)}).variables[${JSON.stringify(key)}]>`
+							: 'string';
+					return `\texport const ${key}: ${type};`;
+				});
+			return [
+				`declare module '$app/env/${visibility}' {`,
+				`\ttype Value<T> = T extends import(${JSON.stringify(name + '/env')}).EnvVarConfig<infer Output> ? Output : never;`,
+				...declarations,
+				'}'
+			].join('\n');
+		})
+		.join('\n');
+	writeChanged(join(directory, 'env.d.ts'), content);
+}

package/src/sync/bin.ts

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+import { readFileSync } from 'node:fs';
+import { own } from '../shared/identity.ts';
+import { cli } from './cli.ts';
+
+const { version } = JSON.parse(
+	readFileSync(new URL('../../package.json', import.meta.url), 'utf8')
+);
+await cli(process.argv.slice(2), version, own);

package/src/sync/cli.ts

@@ -0,0 +1,99 @@
+import {
+	existsSync,
+	mkdirSync,
+	readFileSync,
+	readdirSync,
+	rmdirSync,
+	unlinkSync,
+	writeFileSync
+} from 'node:fs';
+import { parseArgs, styleText } from 'node:util';
+import type { Identity } from '../types/identity.ts';
+
+const help = (command: string) => `
+  Usage: ${command} <command> [options]
+
+  Commands:
+    sync                   Synchronise generated type definitions
+
+  Options:
+    --version, -v          Show version number
+    --help, -h             Show this help message
+
+  Sync Options:
+    --config, -c <config>  Specify a custom Vite config file
+    --mode <mode>          Specify a mode for loading environment variables (default: development)
+`;
+
+function reportError(failure: unknown): void {
+	const error = failure instanceof Error ? failure : new Error(JSON.stringify(failure));
+	if (error.name === 'SyntaxError') throw error;
+	console.error(styleText(['bold', 'red'], `> ${error.message}`));
+	if (error.stack) console.error(styleText('grey', error.stack.split('\n').slice(1).join('\n')));
+	process.exitCode = 1;
+}
+
+async function sync(file: string | undefined, mode: string, fallback: Identity): Promise<void> {
+	const directory = 'node_modules/$app';
+	const tsconfig = `${directory}/tsconfig.json`;
+	const hadDirectory = existsSync(directory);
+	const hadConfig = existsSync(tsconfig);
+	try {
+		if (!hadConfig) {
+			mkdirSync(directory, { recursive: true });
+			writeFileSync(tsconfig, '{}');
+		}
+		const { loadConfig } = await import('../config/file.ts');
+		const { config, vite, api, identity } = await loadConfig(process.cwd(), fallback, file);
+		const { createSync, loadEnvironment } = await import('./index.ts');
+		const { diagnostics } = await import('../shared/diagnostics.ts');
+		const d = diagnostics(identity);
+		const generated = createSync(config, vite.root, d);
+		await generated.initial(mode);
+		const environment = await loadEnvironment(config, vite.root, mode, api, d);
+		generated.writeEnvironment(environment.file, environment.variables);
+	} catch (error) {
+		reportError(error);
+	} finally {
+		if (!hadConfig && existsSync(tsconfig) && readFileSync(tsconfig, 'utf8') === '{}')
+			unlinkSync(tsconfig);
+		if (!hadDirectory && existsSync(directory) && readdirSync(directory).length === 0)
+			rmdirSync(directory);
+	}
+}
+
+function parse(args: string[], usage: string) {
+	try {
+		return parseArgs({
+			args,
+			allowPositionals: true,
+			strict: true,
+			options: {
+				version: { type: 'boolean', short: 'v' },
+				help: { type: 'boolean', short: 'h' },
+				config: { type: 'string', short: 'c' },
+				mode: { type: 'string', default: 'development' }
+			}
+		});
+	} catch (error) {
+		console.error(styleText(['bold', 'red'], `> ${(error as Error).message}`));
+		console.log(usage);
+		process.exit(1);
+	}
+}
+
+export async function cli(args: string[], version: string, identity: Identity): Promise<void> {
+	const usage = help(identity.command);
+	const { values, positionals } = parse(args, usage);
+	if (values.version) {
+		console.log(version);
+	} else if (values.help || positionals.length === 0) {
+		console.log(usage);
+	} else if (positionals[0] === 'sync') {
+		await sync(values.config, values.mode, identity);
+	} else {
+		console.error(styleText(['bold', 'red'], `> Unknown command: ${positionals[0]}`));
+		console.log(usage);
+		process.exitCode = 1;
+	}
+}

package/src/sync/discover.ts

@@ -0,0 +1,258 @@
+import { existsSync, readdirSync, realpathSync, statSync } from 'node:fs';
+import { basename, dirname, join } from 'node:path';
+import { lookup } from '../shared/mime.ts';
+import type { ValidatedConfig } from '../types/builder.ts';
+import type { PageNode, Route, RouteTree } from '../types/internal/routes.ts';
+import { parseRoute, sortRoutes } from '../shared/routing/index.ts';
+import type { Diagnostics } from '../shared/diagnostics.ts';
+import { SyncWarnings } from './warnings.ts';
+import { filesUnder, relativeFile, resolveEntry } from './files.ts';
+import { applyOptions, readOptions } from './options.ts';
+import { validateConflicts, validateRoute } from './route-paths.ts';
+import { SyncErrors } from './errors.ts';
+
+interface PendingRoute {
+	route: Route;
+	layout: PageNode | null;
+	error: PageNode | null;
+	leaf: PageNode | null;
+}
+const componentName = /^\+(page|layout|error)(?:@(.*))?$/;
+const moduleName = /^\+(server|page|layout)(@[^.]+|@)?(\.server)?$/;
+
+function node(depth: number): PageNode {
+	return { depth, parent: null, options: null };
+}
+
+export function discover(config: ValidatedConfig, root: string, d: Diagnostics): RouteTree {
+	const e: SyncErrors = new SyncErrors(d);
+	const w: SyncWarnings = new SyncWarnings(d);
+	const pending: PendingRoute[] = [];
+	const resets = new Map<PageNode, string>();
+	const walk = (
+		directory: string,
+		id: string,
+		depth: number,
+		parent: string | null,
+		ancestors: Set<string>
+	): void => {
+		validateRoute(id, e);
+		const route: Route = {
+			id,
+			parent,
+			segment: id === '/' ? '' : id.slice(id.lastIndexOf('/') + 1),
+			...parseRoute(id),
+			layout: null,
+			error: null,
+			leaf: null,
+			page: null,
+			endpoint: null
+		};
+		const branch: PendingRoute = { route, layout: null, error: null, leaf: null };
+		pending.push(branch);
+		if (!existsSync(directory)) {
+			route.pattern = /^$/;
+			return;
+		}
+		const real = realpathSync(directory);
+		if (ancestors.has(real)) return;
+		const visited = new Set(ancestors).add(real);
+		const entries = readdirSync(directory)
+			.filter((name) => !name.startsWith('_') && (!name.startsWith('.') || name === '.well-known'))
+			.sort();
+		const directories: string[] = [];
+		for (const name of entries) {
+			const file = join(directory, name);
+			if (statSync(file).isDirectory()) {
+				directories.push(name);
+				continue;
+			}
+			const extension = [...config.extensions, ...config.moduleExtensions].find((ext) =>
+				name.endsWith(ext)
+			);
+			if (!extension) continue;
+			const component = config.extensions.includes(extension);
+			const stem = name.slice(0, -extension.length);
+			if (!name.startsWith('+')) {
+				if ((component ? componentName : moduleName).test('+' + stem))
+					w.route_file_prefix_missing({ file, corrected: '+' + name });
+				continue;
+			}
+			if (/\.(?:test|spec|stories)\./.test(name)) continue;
+			if (/\.d\.ts$/.test(name)) {
+				let declaration = name.slice(0, -5);
+				const suffix = [...config.extensions, ...config.moduleExtensions].find((ext) =>
+					declaration.endsWith(ext)
+				);
+				if (suffix) declaration = declaration.slice(0, -suffix.length);
+				if (componentName.test(declaration) || moduleName.test(declaration)) continue;
+			}
+			const match = (component ? componentName : moduleName).exec(stem);
+			const source = relativeFile(root, file);
+			if (!match || (component && match[1] === 'error' && match[2] !== undefined))
+				e.route_file_reserved({ file: source });
+			const role = match[1]!;
+			if (!component && match[2] !== undefined)
+				e.route_named_layout_in_module({
+					file: source,
+					name,
+					layout: match[2],
+					extension: config.extensions[0] ?? ''
+				});
+			const kind = component ? 'component' : role === 'server' || match[3] ? 'server' : 'universal';
+			if (config.router.type === 'hash' && kind === 'server')
+				e.route_server_file_hash_router({ file: source });
+			const duplicate = (type: string, existing: string): never =>
+				e.route_duplicate_files({
+					type,
+					directory: relativeFile(root, directory),
+					existing: basename(existing),
+					file: name
+				});
+			if (role === 'server') {
+				if (route.endpoint) duplicate('endpoint', route.endpoint.file);
+				route.endpoint = { file: source, options: null };
+				continue;
+			}
+			const slot = role === 'page' ? 'leaf' : (role as 'layout' | 'error');
+			const target = (branch[slot] ??= node(depth));
+			if (target[kind])
+				duplicate(`${role} ${kind === 'component' ? 'component' : kind + ' module'}`, target[kind]);
+			target[kind] = source;
+			if (component && match[2] !== undefined) resets.set(target, match[2]);
+		}
+		for (const name of directories)
+			walk(
+				join(directory, name),
+				id === '/' ? '/' + name : id + '/' + name,
+				depth + 1,
+				id,
+				visited
+			);
+	};
+	walk(config.files.routes, '/', 0, null, new Set());
+	if (
+		existsSync(config.files.routes) &&
+		pending.length === 1 &&
+		!pending[0]!.layout &&
+		!pending[0]!.error &&
+		!pending[0]!.leaf &&
+		!pending[0]!.route.endpoint
+	)
+		e.routes_not_found();
+	pending[0]!.layout ??= node(0);
+	pending[0]!.error ??= node(0);
+	const nodes: PageNode[] = [];
+	const add = (entry: PendingRoute, key: 'layout' | 'error' | 'leaf'): void => {
+		if (entry[key]) {
+			entry.route[key] = nodes.length;
+			nodes.push(entry[key]);
+		}
+	};
+	for (const entry of pending) {
+		add(entry, 'layout');
+		add(entry, 'error');
+	}
+	for (const entry of pending) add(entry, 'leaf');
+	const byId = new Map(pending.map((entry) => [entry.route.id, entry]));
+	for (const entry of pending) {
+		const route = entry.route;
+		if (route.leaf === null) continue;
+		const page = (route.page = {
+			layouts: [] as Array<number | undefined>,
+			errors: [] as Array<number | undefined>,
+			leaf: route.leaf
+		});
+		let current: PendingRoute | undefined = entry;
+		let child = entry.leaf!;
+		let reset = resets.get(child);
+		while (current) {
+			if (reset === undefined || current.route.segment === reset) {
+				if (current.layout || current.error) {
+					page.layouts.unshift(current.route.layout ?? undefined);
+					page.errors.unshift(current.route.error ?? undefined);
+				}
+				if (current.layout) {
+					child.parent = current.route.layout;
+					child = current.layout;
+					reset = resets.get(child);
+				} else reset = undefined;
+			}
+			current = current.route.parent === null ? undefined : byId.get(current.route.parent);
+		}
+		if (reset !== undefined)
+			e.route_layout_segment_missing({
+				file: child.component ?? child.universal ?? child.server!,
+				segment: reset
+			});
+	}
+	for (const entry of pending) {
+		if (entry.error) {
+			let parent: PendingRoute | undefined = entry;
+			while (parent && parent.route.layout === null)
+				parent = parent.route.parent === null ? undefined : byId.get(parent.route.parent);
+			entry.error.parent = parent?.route.layout ?? null;
+		}
+		if (entry.layout && entry.layout.parent === null && entry !== pending[0]) {
+			let parent = entry.route.parent === null ? undefined : byId.get(entry.route.parent);
+			while (parent && parent.route.layout === null)
+				parent = parent.route.parent === null ? undefined : byId.get(parent.route.parent);
+			entry.layout.parent = parent?.route.layout ?? null;
+		}
+	}
+	const routes = pending
+		.map(({ route }) => route)
+		.filter(
+			(route) =>
+				route.layout !== null || route.error !== null || route.leaf !== null || route.endpoint
+		);
+	validateConflicts(routes, e);
+	applyOptions(nodes, root);
+	for (const route of routes) {
+		if (!route.endpoint) continue;
+		route.endpoint.options = readOptions(route.endpoint.file, root);
+		if (
+			route.page &&
+			(nodes[route.page.leaf]!.options?.prerender || route.endpoint.options?.prerender)
+		)
+			e.route_prerender_page_and_endpoint({
+				id: route.id,
+				file: basename(route.endpoint.file),
+				extension: config.extensions[0] ?? ''
+			});
+	}
+	const hook = (file: string): string | null => {
+		const entry = resolveEntry(file, config.moduleExtensions);
+		if (entry) return relativeFile(root, entry);
+		const name = basename(file);
+		if (name.startsWith('hooks')) {
+			for (const [typo, description] of [
+				['+' + name, 'Unexpected + prefix'],
+				[name.replace(/^hooks/, 'hook'), 'Missing s suffix']
+			] as const) {
+				const candidate = resolveEntry(join(dirname(file), typo), config.moduleExtensions);
+				if (candidate)
+					w.file_name_misspelled({
+						file: candidate,
+						corrected: basename(candidate).replace(typo, name),
+						description
+					});
+			}
+		}
+		return null;
+	};
+	return {
+		assets: filesUnder(config.files.assets).map((file) => ({
+			file: relativeFile(config.files.assets, file),
+			type: lookup(file) ?? null
+		})),
+		hooks: {
+			client: hook(config.files.hooks.client),
+			server: hook(config.files.hooks.server),
+			universal: hook(config.files.hooks.universal)
+		},
+		params: hook(config.files.params),
+		nodes,
+		routes: sortRoutes(routes)
+	};
+}

package/src/sync/env.ts

@@ -0,0 +1,109 @@
+import path from 'node:path';
+import type { DevEnvironment, RunnableDevEnvironment } from 'vite';
+import { configAliases } from '../config/file.ts';
+import { validate, handleIssues, type EnvironmentIssues } from '../shared/env.ts';
+import type { ValidatedConfig } from '../types/builder.ts';
+import type { EnvVarConfig } from '../types/env.ts';
+import { resolveEntry } from './files.ts';
+import { installation } from './package.ts';
+import type { Diagnostics } from '../shared/diagnostics.ts';
+import { SyncErrors } from './errors.ts';
+
+export interface Environment {
+	variables: Record<string, EnvVarConfig<any>>;
+	values: Record<string, string>;
+	validated: Record<string, unknown>;
+	dependencies: Set<string>;
+	file: string | null;
+}
+
+const reserved = new Set(
+	'arguments await break case catch class const continue debugger default delete do else enum eval export extends false finally for function if implements import in instanceof interface let new null package private protected public return static super switch this throw true try typeof var void while with yield'.split(
+		' '
+	)
+);
+
+export function isRunnable(
+	environment: DevEnvironment | undefined
+): environment is RunnableDevEnvironment {
+	if (!environment || !('runner' in environment)) return false;
+	const runner = environment.runner as RunnableDevEnvironment['runner'];
+	return !!runner && typeof runner.import === 'function';
+}
+
+export function validateEnvironment(environment: Environment, d: Diagnostics): void {
+	const issues: EnvironmentIssues = {};
+	for (const name of Object.keys(environment.variables)) {
+		environment.validated[name] = validate(
+			environment.variables,
+			environment.values[name],
+			name,
+			issues
+		);
+	}
+	handleIssues(issues, d);
+}
+
+export async function loadEnvironment(
+	config: ValidatedConfig,
+	root: string,
+	mode: string,
+	vite: typeof import('vite'),
+	d: Diagnostics
+): Promise<Environment> {
+	const e: SyncErrors = new SyncErrors(d);
+	const file = resolveEntry(path.join(config.files.src, 'env'), config.moduleExtensions);
+	const result: Environment = {
+		variables: {},
+		values: vite.loadEnv(mode, config.env.dir, ''),
+		validated: {},
+		dependencies: new Set(),
+		file
+	};
+	if (!file) return result;
+	const server = await vite.createServer({
+		root,
+		configFile: false,
+		logLevel: 'silent',
+		mode,
+		server: { middlewareMode: true, watch: null },
+		resolve: { alias: configAliases(config, root) },
+		ssr: { noExternal: [installation(root).name, '@vigla/kit'] },
+		plugins: [
+			{
+				name: 'kit:env-discovery',
+				enforce: 'pre',
+				resolveId(id, importer) {
+					if (id === '$app/env') return '\0kit:env-discovery';
+					if (/^\$app\/env\/(private|public)$/.test(id))
+						e.env_circular_import({ type: id.split('/').at(-1)!, importer });
+					if (id.startsWith('$app/') || id.startsWith('$env/')) e.env_app_import();
+				},
+				load(id) {
+					if (id === '\0kit:env-discovery')
+						return `export const browser = false; export const dev = ${mode === 'development'}; export const building = true; export const prerendering = false; export const version = ${JSON.stringify(config.version.name)};`;
+					result.dependencies.add(id);
+				}
+			}
+		]
+	});
+	try {
+		const ssr = server.environments.ssr;
+		if (!isRunnable(ssr)) e.vite_ssr_environment_not_runnable();
+		const module = await ssr.runner.import(file);
+		if (
+			!module.variables ||
+			typeof module.variables !== 'object' ||
+			Array.isArray(module.variables)
+		)
+			e.env_variables_missing({ file });
+		result.variables = module.variables;
+		for (const name of Object.keys(result.variables)) {
+			if (!/^[A-Za-z_$][A-Za-z0-9_$]*$/.test(name) || reserved.has(name))
+				e.env_invalid_variable_name({ name: JSON.stringify(name) });
+		}
+		return result;
+	} finally {
+		await server.close();
+	}
+}