@vigla/kit 0.0.0-stage → 0.1.0

package/src/sync/errors.ts

@@ -0,0 +1,215 @@
+import type { Diagnostics } from '../shared/diagnostics.ts';
+
+interface RouteId {
+	id: string;
+}
+interface FileName {
+	file: string;
+}
+interface EnvCycle {
+	type: string;
+	importer?: string;
+}
+interface VariableName {
+	name: string;
+}
+interface ComponentExtension {
+	extension: string;
+}
+function componentName(extension: string): string {
+	const name = extension.replace(/^\./, '');
+	return name.charAt(0).toUpperCase() + name.slice(1);
+}
+
+export class SyncErrors {
+	private readonly d: Diagnostics;
+	constructor(d: Diagnostics) {
+		this.d = d;
+	}
+	env_invalid_variable_name({ name }: VariableName): never {
+		this.d.raise(
+			'env_invalid_variable_name',
+			`Invalid environment variable name \`${name}\``,
+			this.env_invalid_variable_name
+		);
+	}
+	env_variables_missing({ file }: FileName): never {
+		this.d.raise(
+			'env_variables_missing',
+			`\`${file}\` must export a variables object`,
+			this.env_variables_missing
+		);
+	}
+	env_app_import(): never {
+		this.d.raise(
+			'env_app_import',
+			'Cannot import `$app/*` modules other than `$app/env` inside `src/env`',
+			this.env_app_import
+		);
+	}
+	env_circular_import({ type, importer }: EnvCycle): never {
+		this.d.raise(
+			'env_circular_import',
+			importer
+				? `Module \`${importer}\` imports \`$app/env/${type}\`, which creates a circular dependency with \`src/env\``
+				: `Cannot import \`$app/env/${type}\` inside \`src/env\` or its dependencies because it creates a circular dependency`,
+			this.env_circular_import
+		);
+	}
+	vite_ssr_environment_not_runnable(): never {
+		this.d.raise(
+			'vite_ssr_environment_not_runnable',
+			'The configured Vite SSR environment must be a `RunnableDevEnvironment`',
+			this.vite_ssr_environment_not_runnable
+		);
+	}
+	route_escape_uppercase({ id }: RouteId): never {
+		return this.d.raise(
+			'route_escape_uppercase',
+			`Character escape sequence in \`${id}\` must be lowercase`,
+			this.route_escape_uppercase
+		);
+	}
+	route_escape_invalid({ id }: RouteId): never {
+		return this.d.raise(
+			'route_escape_invalid',
+			`Invalid character escape sequence in \`${id}\``,
+			this.route_escape_invalid
+		);
+	}
+	route_escape_hex_length({ id }: RouteId): never {
+		return this.d.raise(
+			'route_escape_hex_length',
+			`Hexadecimal escape sequence in \`${id}\` must be two characters`,
+			this.route_escape_hex_length
+		);
+	}
+	route_escape_unicode_length({ id }: RouteId): never {
+		return this.d.raise(
+			'route_escape_unicode_length',
+			`Unicode escape sequence in \`${id}\` must be between four and six characters`,
+			this.route_escape_unicode_length
+		);
+	}
+	route_params_adjacent({ id }: RouteId): never {
+		return this.d.raise(
+			'route_params_adjacent',
+			`Invalid route \`${id}\` — parameters must be separated`,
+			this.route_params_adjacent
+		);
+	}
+	route_unbalanced_brackets({ id }: RouteId): never {
+		return this.d.raise(
+			'route_unbalanced_brackets',
+			`Invalid route \`${id}\` — brackets are unbalanced`,
+			this.route_unbalanced_brackets
+		);
+	}
+	route_hash_character({ id, suggestion }: RouteId & { suggestion: string }): never {
+		return this.d.raise(
+			'route_hash_character',
+			`Route \`${id}\` should be renamed to ${suggestion}`,
+			this.route_hash_character
+		);
+	}
+	route_optional_after_rest({ id }: RouteId): never {
+		return this.d.raise(
+			'route_optional_after_rest',
+			`Invalid route \`${id}\` — an \`[[optional]]\` route segment cannot follow a \`[...rest]\` route segment`,
+			this.route_optional_after_rest
+		);
+	}
+	route_optional_rest({ id }: RouteId): never {
+		return this.d.raise(
+			'route_optional_rest',
+			`Invalid route \`${id}\` — a rest route segment is always optional, remove the outer square brackets`,
+			this.route_optional_rest
+		);
+	}
+	route_param_invalid({ id, param }: RouteId & { param: string }): never {
+		return this.d.raise(
+			'route_param_invalid',
+			`Invalid param: ${param} in route \`${id}\`. Params and matcher names can only have underscores, hyphens, and alphanumeric characters.`,
+			this.route_param_invalid
+		);
+	}
+	route_server_file_hash_router({ file }: FileName): never {
+		return this.d.raise(
+			'route_server_file_hash_router',
+			`Cannot use server-only files in an app with \`router.type === 'hash'\`: \`${file}\``,
+			this.route_server_file_hash_router
+		);
+	}
+	route_duplicate_files(values: {
+		type: string;
+		directory: string;
+		existing: string;
+		file: string;
+	}): never {
+		return this.d.raise(
+			'route_duplicate_files',
+			`Multiple ${values.type} files found in \`${values.directory}\` : \`${values.existing}\` and \`${values.file}\``,
+			this.route_duplicate_files
+		);
+	}
+	route_conflict({ first, second }: { first: string; second: string }): never {
+		return this.d.raise(
+			'route_conflict',
+			`The \`${first}\` and \`${second}\` routes conflict with each other`,
+			this.route_conflict
+		);
+	}
+	route_layout_segment_missing({ file, segment }: FileName & { segment: string }): never {
+		return this.d.raise(
+			'route_layout_segment_missing',
+			`\`${file}\` references missing segment \`${segment}\``,
+			this.route_layout_segment_missing
+		);
+	}
+	routes_not_found(): never {
+		return this.d.raise(
+			'routes_not_found',
+			`No routes found. If you are using a custom \`src/routes\` directory, make sure it is specified in your ${this.d.identity.product} Vite plugin options`,
+			this.routes_not_found
+		);
+	}
+	route_prerender_page_and_endpoint({
+		id,
+		file,
+		extension
+	}: RouteId & FileName & ComponentExtension): never {
+		return this.d.raise(
+			'route_prerender_page_and_endpoint',
+			`Cannot prerender a route (\`${id}\`) with both a \`+page${extension}\` and a \`${file}\``,
+			this.route_prerender_page_and_endpoint
+		);
+	}
+	route_file_reserved({ file }: FileName): never {
+		return this.d.raise(
+			'route_file_reserved',
+			`Files prefixed with \`+\` are reserved (saw \`${file}\`)`,
+			this.route_file_reserved
+		);
+	}
+	route_named_layout_in_module({
+		file,
+		name,
+		layout,
+		extension
+	}: FileName & ComponentExtension & { name: string; layout: string }): never {
+		return this.d.raise(
+			'route_named_layout_in_module',
+			`Only ${componentName(extension)} files can reference named layouts. Remove \`${layout}\` from \`${name}\` (at \`${file}\`)`,
+			this.route_named_layout_in_module
+		);
+	}
+	tsconfig_parse_failed({ details }: { details?: string }): never {
+		return this.d.raise(
+			'tsconfig_parse_failed',
+			details === undefined
+				? 'Failed to parse TypeScript config'
+				: `Failed to parse TypeScript config: ${details}`,
+			this.tsconfig_parse_failed
+		);
+	}
+}

package/src/sync/files.ts

@@ -0,0 +1,52 @@
+import {
+	existsSync,
+	mkdirSync,
+	readFileSync,
+	readdirSync,
+	realpathSync,
+	statSync,
+	writeFileSync
+} from 'node:fs';
+import { dirname, join, relative } from 'node:path';
+
+export function posix(file: string): string {
+	return file.replaceAll('\\', '/');
+}
+export function relativeFile(root: string, file: string): string {
+	return posix(relative(root, file));
+}
+export function importPath(from: string, file: string): string {
+	const path = relativeFile(from, file).replace(/\.(?:ts|mts|cts)$/, '.js');
+	return path.startsWith('.') ? path : './' + path;
+}
+export function resolveEntry(file: string, extensions: readonly string[]): string | null {
+	const candidates = [
+		file,
+		...extensions.map((extension) => join(file, 'index' + extension)),
+		...extensions.map((extension) => file + extension)
+	];
+	return (
+		candidates.find((candidate) => existsSync(candidate) && statSync(candidate).isFile()) ?? null
+	);
+}
+export function writeChanged(file: string, text: string): void {
+	if (existsSync(file) && readFileSync(file, 'utf8') === text) return;
+	mkdirSync(dirname(file), { recursive: true });
+	writeFileSync(file, text);
+}
+export function filesUnder(root: string): string[] {
+	if (!existsSync(root)) return [];
+	const files: string[] = [];
+	const walk = (directory: string, ancestors: Set<string>): void => {
+		const real = realpathSync(directory);
+		if (ancestors.has(real)) return;
+		const branch = new Set(ancestors).add(real);
+		for (const entry of readdirSync(directory).sort()) {
+			const file = join(directory, entry);
+			if (statSync(file).isDirectory()) walk(file, branch);
+			else files.push(file);
+		}
+	};
+	walk(root, new Set());
+	return files;
+}

package/src/sync/index.ts

@@ -0,0 +1,48 @@
+import { resolve } from 'node:path';
+import type { Diagnostics } from '../shared/diagnostics.ts';
+import type { ValidatedConfig } from '../types/builder.ts';
+import type { EnvVarConfig } from '../types/env.ts';
+import type { RouteTree } from '../types/internal/routes.ts';
+import { writeAppTypes, writeEnvironment } from './app-types.ts';
+import { discover } from './discover.ts';
+import { installation } from './package.ts';
+import { writeRouteTypes } from './route-types.ts';
+import { writeTsconfig } from './typescript.ts';
+
+export { discover } from './discover.ts';
+export { installation, type Installation } from './package.ts';
+export { analyseOptions } from './options.ts';
+export { loadEnvironment, validateEnvironment, isRunnable, type Environment } from './env.ts';
+export { resolveEntry } from './files.ts';
+export { SyncErrors } from './errors.ts';
+
+export interface Sync {
+	initial(mode: string): Promise<RouteTree>;
+	update(file: string): Promise<RouteTree>;
+	resync(): Promise<RouteTree>;
+	writeEnvironment(entry: string | null, variables: Record<string, EnvVarConfig<any>> | null): void;
+}
+
+export function createSync(config: ValidatedConfig, root: string, d: Diagnostics): Sync {
+	const { name } = installation(root);
+	let entry: string | null = null;
+	let variables: Record<string, EnvVarConfig<any>> | null = null;
+	const sync = async (): Promise<RouteTree> => {
+		const tree = discover(config, root, d);
+		writeTsconfig(config, root, d);
+		writeAppTypes(config, tree, root, name);
+		writeRouteTypes(config, tree, root, name);
+		writeEnvironment(root, name, entry, variables);
+		return tree;
+	};
+	return {
+		initial: (_mode) => sync(),
+		update: (_file) => sync(),
+		resync: sync,
+		writeEnvironment(file, declarations) {
+			entry = file === null ? null : resolve(root, file);
+			variables = declarations;
+			writeEnvironment(root, name, entry, variables);
+		}
+	};
+}

package/src/sync/options.ts

@@ -0,0 +1,104 @@
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { parseSync, type ESTree } from 'vite';
+import type { PageNode, PageOptions } from '../types/internal/routes.ts';
+
+const names = new Set(['ssr', 'csr', 'prerender', 'trailingSlash', 'config', 'entries', 'load']);
+function exportName(node: ESTree.ModuleExportName): string {
+	return node.type === 'Identifier' ? node.name : String(node.value);
+}
+
+export function analyseOptions(filename: string, source: string): PageOptions | null {
+	if (!/ssr|csr|prerender|trailingSlash|config|entries|load|export\s+\*\s+from/.test(source))
+		return {};
+	try {
+		const parsed = parseSync(filename, source, { sourceType: 'module' });
+		if (parsed.errors.length) throw new Error(parsed.errors[0]!.message);
+		const bindings = new Map<string, ESTree.VariableDeclarator | ESTree.Declaration>();
+		const exports = new Map<string, string>();
+		for (const statement of parsed.program.body) {
+			if (statement.type === 'ExportDefaultDeclaration') return null;
+			if (statement.type === 'ExportAllDeclaration') {
+				if (!statement.exported || names.has(exportName(statement.exported))) return null;
+				continue;
+			}
+			if (statement.type === 'ExportNamedDeclaration') {
+				for (const specifier of statement.specifiers) {
+					const name = exportName(specifier.exported);
+					if (!names.has(name)) continue;
+					if (statement.source) return null;
+					exports.set(name, exportName(specifier.local));
+				}
+			}
+			const declaration =
+				statement.type === 'ExportNamedDeclaration' ? statement.declaration : statement;
+			if (declaration?.type === 'VariableDeclaration') {
+				for (const variable of declaration.declarations) {
+					if (variable.id.type !== 'Identifier') {
+						if (statement.type === 'ExportNamedDeclaration') return null;
+						continue;
+					}
+					bindings.set(variable.id.name, variable);
+					if (statement.type === 'ExportNamedDeclaration' && names.has(variable.id.name))
+						exports.set(variable.id.name, variable.id.name);
+				}
+			} else if (
+				declaration?.type === 'FunctionDeclaration' ||
+				declaration?.type === 'ClassDeclaration'
+			) {
+				if (!declaration.id) continue;
+				bindings.set(declaration.id.name, declaration);
+				if (statement.type === 'ExportNamedDeclaration' && names.has(declaration.id.name))
+					exports.set(declaration.id.name, declaration.id.name);
+			}
+		}
+		const result: Record<string, unknown> = {};
+		for (const [name, local] of exports) {
+			const declaration = bindings.get(local);
+			if (!declaration) return null;
+			if (
+				name === 'load' &&
+				local === 'load' &&
+				(declaration.type === 'VariableDeclarator' || declaration.type === 'FunctionDeclaration')
+			) {
+				result.load = null;
+				continue;
+			}
+			if (declaration.type !== 'VariableDeclarator' || declaration.init?.type !== 'Literal')
+				return null;
+			result[name] = declaration.init.value;
+		}
+		return result as PageOptions;
+	} catch (error) {
+		if (error instanceof Error)
+			error.message = `Failed to statically analyse page options for ${filename}. ${error.message}`;
+		throw error;
+	}
+}
+
+export function readOptions(file: string, root: string): PageOptions | null {
+	const source = readFileSync(resolve(root, file), 'utf8');
+	try {
+		return analyseOptions(file, source);
+	} catch {
+		return null;
+	}
+}
+
+export function applyOptions(nodes: PageNode[], root: string): void {
+	const visited = new Set<number>();
+	const visit = (index: number): PageOptions | null => {
+		const node = nodes[index]!;
+		if (visited.has(index)) return node.options;
+		let options: PageOptions | null = node.parent === null ? {} : visit(node.parent);
+		for (const file of [node.server, node.universal]) {
+			if (!file || options === null) continue;
+			const own = readOptions(file, root);
+			options = own === null ? null : { ...options, ...own };
+		}
+		node.options = options;
+		visited.add(index);
+		return options;
+	};
+	for (let index = 0; index < nodes.length; index++) visit(index);
+}

package/src/sync/package.ts

@@ -0,0 +1,41 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+
+const kit = '@vigla/kit';
+
+export interface Installation {
+	readonly name: string;
+	readonly path: string;
+}
+
+interface Manifest {
+	name?: string;
+	dependencies?: Record<string, string>;
+	devDependencies?: Record<string, string>;
+	vigla?: { facade?: string };
+}
+
+function read(file: string): Manifest | undefined {
+	if (!existsSync(file)) return undefined;
+	return JSON.parse(readFileSync(file, 'utf8')) as Manifest;
+}
+
+function installed(name: string, from: string): Manifest | undefined {
+	for (let dir = from; ; dir = dirname(dir)) {
+		const manifest = read(join(dir, 'node_modules', name, 'package.json'));
+		if (manifest !== undefined || dirname(dir) === dir) return manifest;
+	}
+}
+
+export function installation(root: string): Installation {
+	for (let dir = root; ; dir = dirname(dir)) {
+		const manifest = read(join(dir, 'package.json'));
+		const names = Object.keys({ ...manifest?.dependencies, ...manifest?.devDependencies });
+		for (const name of names) {
+			const found = installed(name, dir);
+			if (found?.name === kit) return { name, path: name };
+			if (found?.vigla?.facade === kit) return { name, path: `${name} > ${kit}` };
+		}
+		if (dirname(dir) === dir) return { name: kit, path: kit };
+	}
+}

package/src/sync/proxy.ts

@@ -0,0 +1,180 @@
+import { readFileSync } from 'node:fs';
+import { basename, dirname, join, resolve } from 'node:path';
+import { parseSync, type ESTree } from 'vite';
+import { importPath, writeChanged } from './files.ts';
+
+export interface TypeProxy {
+	exports: Set<string>;
+	module: string;
+	file?: string;
+}
+interface Change {
+	start: number;
+	end: number;
+	text: string;
+}
+type FunctionNode = ESTree.Function | ESTree.ArrowFunctionExpression;
+
+function isFunction(node: ESTree.Expression | ESTree.Declaration | null): node is FunctionNode {
+	return (
+		node?.type === 'ArrowFunctionExpression' ||
+		node?.type === 'FunctionExpression' ||
+		node?.type === 'FunctionDeclaration'
+	);
+}
+function bindings(pattern: ESTree.BindingPattern | ESTree.BindingRestElement): string[] {
+	if (pattern.type === 'Identifier') return [pattern.name];
+	if (pattern.type === 'AssignmentPattern') return bindings(pattern.left);
+	if (pattern.type === 'RestElement') return bindings(pattern.argument);
+	if (pattern.type === 'ArrayPattern')
+		return pattern.elements.flatMap((item) => (item ? bindings(item) : []));
+	if (pattern.type === 'ObjectPattern')
+		return pattern.properties.flatMap((property) =>
+			bindings(property.type === 'RestElement' ? property.argument : property.value)
+		);
+	return [];
+}
+
+export function createProxy(file: string, root: string, output: string): TypeProxy | null {
+	const original = readFileSync(join(root, file), 'utf8');
+	const absolute = join(root, file);
+	const parsed = parseSync(absolute, original, { sourceType: 'module' });
+	if (parsed.errors.length) return null;
+	const exports = new Map<string, string>();
+	for (const statement of parsed.program.body) {
+		if (statement.type !== 'ExportNamedDeclaration') continue;
+		for (const specifier of statement.specifiers) {
+			const exported =
+				specifier.exported.type === 'Identifier'
+					? specifier.exported.name
+					: String(specifier.exported.value);
+			const local =
+				specifier.local.type === 'Identifier'
+					? specifier.local.name
+					: String(specifier.local.value);
+			exports.set(exported, local);
+		}
+		const declaration = statement.declaration;
+		if (declaration?.type === 'VariableDeclaration')
+			for (const variable of declaration.declarations)
+				for (const name of bindings(variable.id)) exports.set(name, name);
+		if (declaration?.type === 'FunctionDeclaration' && declaration.id)
+			exports.set(declaration.id.name, declaration.id.name);
+	}
+	const targets = new Set([exports.get('load'), exports.get('actions')]);
+	const edits: Change[] = [];
+	const parameter = (fn: FunctionNode, type: string): boolean => {
+		const first = fn.params[0];
+		if (!first) return false;
+		const value = first.type === 'AssignmentPattern' ? first.left : first;
+		if ('typeAnnotation' in value && value.typeAnnotation) return false;
+		const bare =
+			fn.type === 'ArrowFunctionExpression' && original.slice(fn.start, first.start).trim() === '';
+		if (bare) edits.push({ start: first.start, end: first.start, text: '(' });
+		edits.push({ start: value.end, end: value.end, text: `: ${type}${bare ? ')' : ''}` });
+		return true;
+	};
+	const docType = (start: number, fn: FunctionNode | null): string | null => {
+		const comment = parsed.comments
+			.filter((comment) => comment.end <= start && /^\s*$/.test(original.slice(comment.end, start)))
+			.at(-1);
+		if (!comment) return null;
+		const text = original.slice(comment.start, comment.end);
+		const at = text.indexOf('@type');
+		if (at < 0) return null;
+		const begin = text.indexOf('{', at);
+		let depth = 1;
+		let end = begin + 1;
+		while (end < text.length && depth) {
+			if (text[end] === '{') depth++;
+			if (text[end] === '}') depth--;
+			end++;
+		}
+		if (depth || begin < 0) return null;
+		const type = text.slice(begin + 1, end - 1);
+		const first = fn?.params[0];
+		const name = first?.type === 'Identifier' ? first.name : 'event';
+		edits.push({
+			start: comment.start,
+			end: comment.end,
+			text: first ? `/** @param {Parameters<${type}>[0]} ${name} */` : ''
+		});
+		return type;
+	};
+	let unused = '';
+	for (const statement of parsed.program.body) {
+		const declaration =
+			statement.type === 'ExportNamedDeclaration' ? statement.declaration : statement;
+		if (
+			declaration?.type === 'FunctionDeclaration' &&
+			declaration.id &&
+			declaration.id.name === exports.get('load')
+		)
+			docType(statement.start, declaration);
+		if (declaration?.type !== 'VariableDeclaration') continue;
+		for (const variable of declaration.declarations) {
+			if (variable.id.type !== 'Identifier' || !targets.has(variable.id.name)) continue;
+			const annotation = variable.id.typeAnnotation;
+			const init = variable.init;
+			const action = variable.id.name === exports.get('actions');
+			const type = annotation
+				? original.slice(annotation.typeAnnotation.start, annotation.typeAnnotation.end)
+				: null;
+			if (annotation) edits.push({ start: annotation.start, end: annotation.end, text: '' });
+			const doc = docType(statement.start, !action && isFunction(init) ? init : null);
+			if (!action && type && isFunction(init) && !parameter(init, `Parameters<${type}>[0]`))
+				unused += `;null as unknown as ${type};`;
+			if (action && (type || doc) && init?.type === 'ObjectExpression') {
+				for (const property of init.properties) {
+					if (property.type !== 'Property' || !isFunction(property.value)) continue;
+					if (type) parameter(property.value, "import('./$types').RequestEvent");
+					else if (!docType(property.start, property.value) && property.value.params.length) {
+						const first = property.value.params[0]!;
+						const name = first.type === 'Identifier' ? first.name : 'event';
+						edits.push({
+							start: property.value.start,
+							end: property.value.start,
+							text: `/** @param {import('./$types').RequestEvent} ${name} */ `
+						});
+					}
+				}
+				if (type) unused += `;null as unknown as ${type};`;
+			}
+		}
+	}
+	if (!edits.length)
+		return { exports: new Set(exports.keys()), module: importPath(output, absolute) };
+	for (const statement of parsed.program.body) {
+		const source =
+			statement.type === 'ImportDeclaration' ||
+			statement.type === 'ExportNamedDeclaration' ||
+			statement.type === 'ExportAllDeclaration'
+				? statement.source
+				: null;
+		if (
+			source &&
+			typeof source.value === 'string' &&
+			source.value.startsWith('.') &&
+			!source.value.includes('$types')
+		)
+			edits.push({
+				start: source.start,
+				end: source.end,
+				text: JSON.stringify(importPath(output, resolve(dirname(absolute), source.value)))
+			});
+	}
+	let code = original;
+	for (const edit of edits.sort((a, b) => b.start - a.start || b.end - a.end))
+		code = code.slice(0, edit.start) + edit.text + code.slice(edit.end);
+	code += unused;
+	if (code.startsWith('// @ts-check'))
+		code = code.replace('// @ts-check', '// @ts-check\n// @ts-nocheck');
+	else code = '// @ts-nocheck\n' + code;
+	const name = 'proxy' + basename(file);
+	writeChanged(join(output, name), code);
+	return {
+		exports: new Set(exports.keys()),
+		module: './' + name.replace(/\.(?:ts|mts|cts)$/, '.js'),
+		file: join(output, name)
+	};
+}