proteum 2.4.4 → 2.5.1

package/cli/compiler/common/generatedRouteModules.ts

@@ -10,13 +10,13 @@ type TRouteRuntime = 'client' | 'server';
 export type TIndexedSourceLocation = { line: number; column: number };
 export type TIndexedRouteTargetResolution = 'literal' | 'static-expression' | 'dynamic-expression';
 
-type TImportedService = { importedName: string; localName: string };
-
-type TRouteDefinition = {
-    args: ts.NodeArray<ts.Expression>;
+type TExplicitRouteDefinition = {
     methodName: string;
-    serviceLocalName: string;
-    callExpression: ts.CallExpression;
+    sourceLocation: TIndexedSourceLocation;
+    targetExpression: ts.Expression;
+    optionsExpression?: ts.Expression;
+    optionsArg?: ts.ObjectLiteralExpression;
+    hasData: boolean;
 };
 
 export type TIndexedRouteDefinition = {
@@ -44,11 +44,16 @@ type TWriteGeneratedRouteModuleOptions = {
     side: TRouteSide;
     sourceFilepath: string;
     clientRoute?: TGeneratedClientRouteModuleOptions;
-    routeSourceFilepaths?: Set<string>;
 };
 
-const clientRouterImportSources = new Set(['@client/router', '@/client/router']);
-const routerMethods = new Set(['page', 'error', 'get', 'post', 'put', 'delete', 'patch']);
+const legacyRouterMethods = new Set(['page', 'error', 'all', 'options', 'get', 'post', 'put', 'delete', 'patch', 'express']);
+const routeDefinitionHelpers = new Set([
+    'definePageRoute',
+    'defineErrorRoute',
+    'defineServerRoute',
+    'defineServerRoutes',
+]);
+const serverRouteMethods = new Set(['*', 'all', 'options', 'get', 'post', 'put', 'patch', 'delete']);
 
 const parseSourceFile = (filepath: string, code: string) =>
     ts.createSourceFile(
@@ -168,6 +173,108 @@ const tryEvaluateStaticExpression = (
     return undefined;
 };
 
+const unwrapStaticExpression = (node: ts.Expression): ts.Expression => {
+    if (ts.isParenthesizedExpression(node)) return unwrapStaticExpression(node.expression);
+    if (ts.isAsExpression(node)) return unwrapStaticExpression(node.expression);
+    if (ts.isTypeAssertionExpression(node)) return unwrapStaticExpression(node.expression);
+    if (ts.isSatisfiesExpression(node)) return unwrapStaticExpression(node.expression);
+    if (ts.isNonNullExpression(node)) return unwrapStaticExpression(node.expression);
+
+    return node;
+};
+
+const isStaticSerializableExpression = (
+    node: ts.Expression,
+    bindingInitializers: Map<string, ts.Expression>,
+    resolvedBindings: Map<string, string | number | undefined>,
+    activeBindings = new Set<string>(),
+): boolean => {
+    const expression = unwrapStaticExpression(node);
+
+    if (
+        ts.isStringLiteral(expression) ||
+        ts.isNoSubstitutionTemplateLiteral(expression) ||
+        ts.isNumericLiteral(expression) ||
+        expression.kind === ts.SyntaxKind.TrueKeyword ||
+        expression.kind === ts.SyntaxKind.FalseKeyword ||
+        expression.kind === ts.SyntaxKind.NullKeyword
+    ) {
+        return true;
+    }
+
+    if (
+        ts.isPrefixUnaryExpression(expression) ||
+        ts.isBinaryExpression(expression) ||
+        ts.isTemplateExpression(expression)
+    ) {
+        return tryEvaluateStaticExpression(expression, bindingInitializers, resolvedBindings) !== undefined;
+    }
+
+    if (ts.isIdentifier(expression)) {
+        if (activeBindings.has(expression.text)) return false;
+
+        const initializer = bindingInitializers.get(expression.text);
+        if (!initializer) return false;
+
+        activeBindings.add(expression.text);
+        const isStatic = isStaticSerializableExpression(initializer, bindingInitializers, resolvedBindings, activeBindings);
+        activeBindings.delete(expression.text);
+
+        return isStatic;
+    }
+
+    if (ts.isArrayLiteralExpression(expression)) {
+        return expression.elements.every((element) => {
+            if (ts.isSpreadElement(element)) return false;
+
+            return isStaticSerializableExpression(element, bindingInitializers, resolvedBindings, activeBindings);
+        });
+    }
+
+    if (ts.isObjectLiteralExpression(expression)) {
+        return expression.properties.every((property) => {
+            if (ts.isPropertyAssignment(property)) {
+                if (ts.isComputedPropertyName(property.name)) return false;
+
+                return isStaticSerializableExpression(
+                    property.initializer,
+                    bindingInitializers,
+                    resolvedBindings,
+                    activeBindings,
+                );
+            }
+
+            if (ts.isShorthandPropertyAssignment(property)) {
+                return isStaticSerializableExpression(
+                    property.name,
+                    bindingInitializers,
+                    resolvedBindings,
+                    activeBindings,
+                );
+            }
+
+            return false;
+        });
+    }
+
+    return false;
+};
+
+const assertStaticSerializableMetadata = (
+    sourceFile: ts.SourceFile,
+    expression: ts.Expression,
+    label: string,
+    bindingInitializers: Map<string, ts.Expression>,
+    resolvedBindings: Map<string, string | number | undefined>,
+) => {
+    if (isStaticSerializableExpression(expression, bindingInitializers, resolvedBindings)) return;
+
+    const location = getNodeLocation(sourceFile, expression);
+    throw new Error(
+        `${sourceFile.fileName}:${location.line}:${location.column} ${label} must be a serializable static literal or const-only expression. Runtime app, request, service, import, function, and property references are only allowed inside data/render/handler callbacks.`,
+    );
+};
+
 const collectStaticBindings = (sourceFile: ts.SourceFile) => {
     const bindingInitializers = new Map<string, ts.Expression>();
     const resolvedBindings = new Map<string, string | number | undefined>();
@@ -198,369 +305,336 @@ const collectStaticBindings = (sourceFile: ts.SourceFile) => {
     return resolvedBindings;
 };
 
-const getRouteOptionMetadata = (node: ts.ObjectLiteralExpression | undefined) => {
-    const optionKeys = node ? getObjectLiteralPropertyKeys(node) : [];
-    const normalizedOptionKeys: string[] = [];
-    const invalidOptionKeys: string[] = [];
-    const reservedOptionKeys: string[] = [];
+const collectStaticBindingInitializers = (sourceFile: ts.SourceFile) => {
+    const bindingInitializers = new Map<string, ts.Expression>();
 
-    for (const optionKey of optionKeys) {
-        try {
-            const normalizedOptionKey = getRouteOptionKey(optionKey);
+    for (const statement of sourceFile.statements) {
+        if (!ts.isVariableStatement(statement)) continue;
+        if (!(statement.declarationList.flags & ts.NodeFlags.Const)) continue;
 
-            if (normalizedOptionKey) {
-                normalizedOptionKeys.push(normalizedOptionKey);
-                continue;
-            }
+        for (const declaration of statement.declarationList.declarations) {
+            if (!ts.isIdentifier(declaration.name) || !declaration.initializer) continue;
 
-            invalidOptionKeys.push(optionKey);
-        } catch (error) {
-            reservedOptionKeys.push(optionKey);
+            bindingInitializers.set(declaration.name.text, declaration.initializer);
         }
     }
 
-    return { optionKeys, normalizedOptionKeys, invalidOptionKeys, reservedOptionKeys };
+    return bindingInitializers;
 };
 
-const buildInjectedRouteMetadata = (sourceFilepath: string, sourceLocation: TIndexedSourceLocation, extra: string[] = []) =>
-    `{ filepath: ${JSON.stringify(normalizeFilepath(sourceFilepath))}, sourceLocation: { line: ${sourceLocation.line}, column: ${sourceLocation.column} }${extra.length > 0 ? `, ${extra.join(', ')}` : ''} }`;
-
-const routeModuleExtensions = ['.ts', '.tsx', '.js', '.jsx'];
+const getPropertyAssignment = (node: ts.ObjectLiteralExpression, propertyName: string) => {
+    for (const property of node.properties) {
+        if (!ts.isPropertyAssignment(property)) continue;
 
-const resolveRouteImport = (sourceFilepath: string, moduleSpecifier: string, routeSourceFilepaths?: Set<string>) => {
-    if (!routeSourceFilepaths || !moduleSpecifier.startsWith('.')) return undefined;
-
-    const absoluteBasePath = path.resolve(path.dirname(sourceFilepath), moduleSpecifier);
-    const candidates = [
-        absoluteBasePath,
-        ...routeModuleExtensions.map((extension) => absoluteBasePath + extension),
-        ...routeModuleExtensions.map((extension) => path.join(absoluteBasePath, `index${extension}`)),
-    ];
+        const key = getObjectLiteralPropertyKey(property.name);
+        if (key === propertyName) return property.initializer;
+    }
 
-    return candidates.find((candidate) => routeSourceFilepaths.has(normalizeFilepath(candidate)));
+    return undefined;
 };
 
-const addImportedService = (importedServices: TImportedService[], importedName: string, localName: string) => {
-    if (
-        importedServices.some(
-            (importedService) =>
-                importedService.importedName === importedName && importedService.localName === localName,
-        )
-    ) {
-        return;
-    }
-
-    importedServices.push({ importedName, localName });
+const getCallExpressionName = (node: ts.Expression) => {
+    if (ts.isIdentifier(node)) return node.text;
+    if (ts.isPropertyAccessExpression(node)) return node.name.text;
+    return undefined;
 };
 
-const collectImportedServices = (
+const resolveIdentifierExpression = (
+    expression: ts.Expression,
     sourceFile: ts.SourceFile,
-    side: TRouteSide,
-    stripRanges: Array<{ start: number; end: number }>,
-) => {
-    const importedServices: TImportedService[] = [];
-
-    for (const statement of sourceFile.statements) {
-        if (!ts.isImportDeclaration(statement)) continue;
-        if (!statement.importClause) continue;
-        if (!ts.isStringLiteral(statement.moduleSpecifier)) continue;
+): ts.Expression => {
+    const unwrapped = unwrapStaticExpression(expression);
+    if (!ts.isIdentifier(unwrapped)) return unwrapped;
 
-        const source = statement.moduleSpecifier.text;
-        const isClientRouterImport = side === 'client' && clientRouterImportSources.has(source);
-
-        if (source !== '@app' && !isClientRouterImport) continue;
-
-        if (isClientRouterImport && statement.importClause.name) {
-            addImportedService(importedServices, 'Router', statement.importClause.name.text);
-        }
+    const bindingInitializers = collectStaticBindingInitializers(sourceFile);
+    return bindingInitializers.get(unwrapped.text) || unwrapped;
+};
 
-        for (const specifier of statement.importClause.namedBindings
-            ? ts.isNamedImports(statement.importClause.namedBindings)
-                ? statement.importClause.namedBindings.elements
-                : []
-            : []) {
-            addImportedService(
-                importedServices,
-                specifier.propertyName?.text || specifier.name.text,
-                specifier.name.text,
-            );
+const getDefaultRouteDefinitionExpression = (sourceFile: ts.SourceFile) => {
+    for (const statement of sourceFile.statements) {
+        if (ts.isExportAssignment(statement) && !statement.isExportEquals) {
+            return resolveIdentifierExpression(statement.expression, sourceFile);
         }
-
-        stripRanges.push({ start: statement.getStart(sourceFile), end: statement.getEnd() });
     }
 
-    return importedServices;
-};
-
-const collectNestedRouteImports = (
-    sourceFile: ts.SourceFile,
-    sourceFilepath: string,
-    routeSourceFilepaths: Set<string> | undefined,
-    stripRanges: Array<{ start: number; end: number }>,
-) => {
     for (const statement of sourceFile.statements) {
-        if (!ts.isImportDeclaration(statement)) continue;
-        if (statement.importClause) continue;
-        if (!ts.isStringLiteral(statement.moduleSpecifier)) continue;
-
-        const routeImportPath = resolveRouteImport(
-            sourceFilepath,
-            statement.moduleSpecifier.text,
-            routeSourceFilepaths,
-        );
-
-        if (!routeImportPath) continue;
+        if (!ts.isVariableStatement(statement)) continue;
+        if (!statement.modifiers?.some((modifier) => modifier.kind === ts.SyntaxKind.DefaultKeyword)) continue;
 
-        stripRanges.push({ start: statement.getStart(sourceFile), end: statement.getEnd() });
+        for (const declaration of statement.declarationList.declarations) {
+            if (declaration.initializer) return declaration.initializer;
+        }
     }
-};
 
-const collectRouteDefinitions = (
-    sourceFile: ts.SourceFile,
-    importedServices: TImportedService[],
-    stripRanges: Array<{ start: number; end: number }>,
-) => {
-    const importedServiceNames = new Set(importedServices.map((importedService) => importedService.localName));
-    const definitions: TRouteDefinition[] = [];
+    return undefined;
+};
 
+const assertNoLegacyRouteMagic = (sourceFile: ts.SourceFile, side: TRouteSide) => {
     for (const statement of sourceFile.statements) {
+        if (ts.isImportDeclaration(statement) && ts.isStringLiteral(statement.moduleSpecifier)) {
+            const source = statement.moduleSpecifier.text;
+
+            if (source === '@app') {
+                const location = getNodeLocation(sourceFile, statement);
+                throw new Error(
+                    `${sourceFile.fileName}:${location.line}:${location.column} imports @app. Route modules must export define*Route definitions and receive app services through typed runtime callback context.`,
+                );
+            }
+        }
+
         if (!ts.isExpressionStatement(statement)) continue;
         if (!ts.isCallExpression(statement.expression)) continue;
         if (!ts.isPropertyAccessExpression(statement.expression.expression)) continue;
 
         const callee = statement.expression.expression;
         if (!ts.isIdentifier(callee.expression)) continue;
-        if (!routerMethods.has(callee.name.text)) continue;
-        if (!importedServiceNames.has(callee.expression.text)) continue;
-
-        definitions.push({
-            args: statement.expression.arguments,
-            methodName: callee.name.text,
-            serviceLocalName: callee.expression.text,
-            callExpression: statement.expression,
-        });
+        if (callee.expression.text !== 'Router') continue;
+        if (!legacyRouterMethods.has(callee.name.text)) continue;
 
-        stripRanges.push({ start: statement.getStart(sourceFile), end: statement.getEnd() });
+        const location = getNodeLocation(sourceFile, statement);
+        throw new Error(
+            `${sourceFile.fileName}:${location.line}:${location.column} uses top-level ${callee.expression.text}.${callee.name.text}(...). Route modules must export define*Route definitions instead.`,
+        );
     }
-
-    return definitions;
 };
 
-const buildRemainingSource = (sourceFile: ts.SourceFile, stripRanges: Array<{ start: number; end: number }>) => {
-    const sortedRanges = stripRanges.sort((a, b) => a.start - b.start);
-    const chunks: string[] = [];
-    let cursor = 0;
+const parseExplicitRouteCall = (
+    sourceFile: ts.SourceFile,
+    side: TRouteSide,
+    node: ts.Expression,
+): TExplicitRouteDefinition[] => {
+    const expression = unwrapStaticExpression(resolveIdentifierExpression(node, sourceFile));
+    const staticBindingInitializers = collectStaticBindingInitializers(sourceFile);
+    const staticBindings = collectStaticBindings(sourceFile);
 
-    for (const range of sortedRanges) {
-        if (cursor < range.start) chunks.push(sourceFile.text.slice(cursor, range.start));
-        cursor = Math.max(cursor, range.end);
+    if (!ts.isCallExpression(expression)) {
+        throw new Error(`Route module ${sourceFile.fileName} must default-export a define*Route(...) call.`);
     }
 
-    if (cursor < sourceFile.text.length) {
-        chunks.push(sourceFile.text.slice(cursor));
+    const helperName = getCallExpressionName(expression.expression);
+    if (!helperName || !routeDefinitionHelpers.has(helperName)) {
+        throw new Error(`Route module ${sourceFile.fileName} must default-export a define*Route(...) call.`);
     }
 
-    return chunks.join('').trim();
-};
+    if (helperName === 'defineServerRoutes') {
+        if (side !== 'server') {
+            throw new Error(`Client route module ${sourceFile.fileName} cannot export defineServerRoutes(...).`);
+        }
 
-const normalizeRelativeImportPath = (value: string) => (value.startsWith('.') ? value : `./${value}`);
+        const [routesArg] = [...expression.arguments];
+        const routeListExpression =
+            routesArg && ts.isArrayLiteralExpression(routesArg)
+                ? routesArg
+                : routesArg &&
+                    (ts.isArrowFunction(routesArg) || ts.isFunctionExpression(routesArg)) &&
+                    ts.isArrayLiteralExpression(routesArg.body)
+                  ? routesArg.body
+                  : undefined;
+
+        if (!routeListExpression) {
+            throw new Error(`defineServerRoutes(...) in ${sourceFile.fileName} must receive a static array literal or a factory returning one.`);
+        }
 
-const rebaseRelativeModuleSpecifiers = (code: string, outputFilepath: string, sourceFilepath: string) => {
-    const outputDir = path.dirname(outputFilepath);
-    const sourceDir = path.dirname(sourceFilepath);
-    const sourceFile = parseSourceFile(outputFilepath, code);
-    const replacements: Array<{ start: number; end: number; value: string }> = [];
+        return routeListExpression.elements.map((element) => parseExplicitRouteCall(sourceFile, side, element)).flat();
+    }
 
-    const addReplacement = (literal: ts.StringLiteralLike) => {
-        if (!literal.text.startsWith('.')) return;
+    const [definitionArg] = [...expression.arguments];
+    if (!definitionArg || !ts.isObjectLiteralExpression(definitionArg)) {
+        throw new Error(`${helperName}(...) in ${sourceFile.fileName} must receive an object literal.`);
+    }
 
-        const absoluteTarget = path.resolve(sourceDir, literal.text);
-        const nextRelativePath = normalizeRelativeImportPath(
-            path.relative(outputDir, absoluteTarget).replace(/\\/g, '/'),
+    const sourceLocation = getNodeLocation(sourceFile, expression);
+    const optionsExpression = getPropertyAssignment(definitionArg, 'options');
+    const resolvedOptionsExpression = optionsExpression
+        ? unwrapStaticExpression(resolveIdentifierExpression(optionsExpression, sourceFile))
+        : undefined;
+    const optionsArg =
+        resolvedOptionsExpression && ts.isObjectLiteralExpression(resolvedOptionsExpression)
+            ? resolvedOptionsExpression
+            : undefined;
+
+    if (optionsExpression) {
+        assertStaticSerializableMetadata(
+            sourceFile,
+            optionsExpression,
+            `${helperName} options`,
+            staticBindingInitializers,
+            staticBindings,
         );
 
-        replacements.push({
-            start: literal.getStart(sourceFile),
-            end: literal.getEnd(),
-            value: JSON.stringify(nextRelativePath),
-        });
-    };
-
-    const visit = (node: ts.Node) => {
-        if (
-            (ts.isImportDeclaration(node) || ts.isExportDeclaration(node)) &&
-            node.moduleSpecifier &&
-            ts.isStringLiteral(node.moduleSpecifier)
-        ) {
-            addReplacement(node.moduleSpecifier);
-        }
-
-        if (
-            ts.isCallExpression(node) &&
-            node.arguments.length > 0 &&
-            ts.isStringLiteral(node.arguments[0]) &&
-            (node.expression.kind === ts.SyntaxKind.ImportKeyword ||
-                (ts.isIdentifier(node.expression) && node.expression.text === 'require'))
-        ) {
-            addReplacement(node.arguments[0]);
-        }
-
-        if (
-            ts.isImportTypeNode(node) &&
-            ts.isLiteralTypeNode(node.argument) &&
-            ts.isStringLiteral(node.argument.literal)
-        ) {
-            addReplacement(node.argument.literal);
+        if (!optionsArg) {
+            const location = getNodeLocation(sourceFile, optionsExpression);
+            throw new Error(
+                `${sourceFile.fileName}:${location.line}:${location.column} ${helperName} options must resolve to a static object literal.`,
+            );
         }
+    }
 
-        ts.forEachChild(node, visit);
-    };
-
-    ts.forEachChild(sourceFile, visit);
-
-    return replacements
-        .sort((a, b) => b.start - a.start)
-        .reduce(
-            (currentCode, replacement) =>
-                currentCode.slice(0, replacement.start) + replacement.value + currentCode.slice(replacement.end),
-            code,
+    if (helperName === 'definePageRoute') {
+        if (side !== 'client') throw new Error(`Server route module ${sourceFile.fileName} cannot export definePageRoute(...).`);
+
+        const pathExpression = getPropertyAssignment(definitionArg, 'path');
+        const dataExpression = getPropertyAssignment(definitionArg, 'data');
+        const renderExpression = getPropertyAssignment(definitionArg, 'render');
+        if (!pathExpression) throw new Error(`definePageRoute(...) in ${sourceFile.fileName} is missing path.`);
+        if (!optionsExpression) throw new Error(`definePageRoute(...) in ${sourceFile.fileName} is missing options.`);
+        if (!dataExpression) throw new Error(`definePageRoute(...) in ${sourceFile.fileName} is missing data.`);
+        if (!renderExpression) throw new Error(`definePageRoute(...) in ${sourceFile.fileName} is missing render.`);
+
+        assertStaticSerializableMetadata(
+            sourceFile,
+            pathExpression,
+            'definePageRoute path',
+            staticBindingInitializers,
+            staticBindings,
         );
-};
 
-const buildDestructuring = (importedServices: TImportedService[]) => {
-    const parts = importedServices.map(({ importedName, localName }) =>
-        importedName === localName ? importedName : `${importedName}: ${localName}`,
-    );
-
-    return `const { ${parts.join(', ')} } = app;`;
-};
+        return [
+            {
+                methodName: 'page',
+                sourceLocation,
+                targetExpression: pathExpression,
+                optionsExpression,
+                optionsArg,
+                hasData: dataExpression?.kind !== ts.SyntaxKind.NullKeyword,
+            },
+        ];
+    }
 
-const getClientRouteSignature = (sourceFile: ts.SourceFile, definition: TRouteDefinition) => {
-    const [, ...routeArgs] = [...definition.args];
+    if (helperName === 'defineErrorRoute') {
+        if (side !== 'client') throw new Error(`Server route module ${sourceFile.fileName} cannot export defineErrorRoute(...).`);
+
+        const codeExpression = getPropertyAssignment(definitionArg, 'code');
+        const renderExpression = getPropertyAssignment(definitionArg, 'render');
+        if (!codeExpression) throw new Error(`defineErrorRoute(...) in ${sourceFile.fileName} is missing code.`);
+        if (!optionsExpression) throw new Error(`defineErrorRoute(...) in ${sourceFile.fileName} is missing options.`);
+        if (!renderExpression) throw new Error(`defineErrorRoute(...) in ${sourceFile.fileName} is missing render.`);
+
+        assertStaticSerializableMetadata(
+            sourceFile,
+            codeExpression,
+            'defineErrorRoute code',
+            staticBindingInitializers,
+            staticBindings,
+        );
 
-    if (definition.methodName === 'error') {
-        if (routeArgs.length === 2) {
-            return {
+        return [
+            {
+                methodName: 'error',
+                sourceLocation,
+                targetExpression: codeExpression,
+                optionsExpression,
+                optionsArg,
                 hasData: false,
-                optionsExpression: routeArgs[0],
-                optionsArg: ts.isObjectLiteralExpression(routeArgs[0]) ? routeArgs[0] : undefined,
-                renderArg: routeArgs[1],
-            };
-        }
-
-        throw new Error(
-            `Unsupported client error route signature in ${sourceFile.fileName}. Expected Router.error(code, options, render).`,
-        );
+            },
+        ];
     }
 
-    if (routeArgs.length === 3) {
-        return {
-            hasData: routeArgs[1].kind !== ts.SyntaxKind.NullKeyword,
-            optionsExpression: routeArgs[0],
-            optionsArg: ts.isObjectLiteralExpression(routeArgs[0]) ? routeArgs[0] : undefined,
-            dataArg: routeArgs[1],
-            renderArg: routeArgs[2],
-        };
-    }
+    const methodExpression = getPropertyAssignment(definitionArg, 'method');
+    const pathExpression = getPropertyAssignment(definitionArg, 'path');
+    const handlerExpression = getPropertyAssignment(definitionArg, 'handler');
+    if (!methodExpression) throw new Error(`defineServerRoute(...) in ${sourceFile.fileName} is missing method.`);
+    if (!pathExpression) throw new Error(`defineServerRoute(...) in ${sourceFile.fileName} is missing path.`);
+    if (!optionsExpression) throw new Error(`defineServerRoute(...) in ${sourceFile.fileName} is missing options.`);
+    if (!handlerExpression) throw new Error(`defineServerRoute(...) in ${sourceFile.fileName} is missing handler.`);
+
+    assertStaticSerializableMetadata(
+        sourceFile,
+        methodExpression,
+        'defineServerRoute method',
+        staticBindingInitializers,
+        staticBindings,
+    );
+    assertStaticSerializableMetadata(
+        sourceFile,
+        pathExpression,
+        'defineServerRoute path',
+        staticBindingInitializers,
+        staticBindings,
+    );
 
-    throw new Error(
-        `Unsupported client page route signature in ${sourceFile.fileName}. Expected Router.page(path, options, data, render).`,
+    const methodName = tryEvaluateStaticExpression(
+        methodExpression,
+        staticBindingInitializers,
+        staticBindings,
     );
-};
 
-const buildClientRegisterArgs = (
-    sourceFile: ts.SourceFile,
-    definition: TRouteDefinition,
-    clientRoute: TGeneratedClientRouteModuleOptions,
-) => {
-    const { optionsExpression, renderArg } = getClientRouteSignature(sourceFile, definition);
-    const sourceLocation = getNodeLocation(sourceFile, definition.callExpression);
-    const injectedOptions = buildInjectedRouteMetadata(sourceFile.fileName, sourceLocation, [
-        `id: ${JSON.stringify(clientRoute.chunkId)}`,
-    ]);
+    if (typeof methodName !== 'string') {
+        throw new Error(`defineServerRoute(...) in ${sourceFile.fileName} must use a static string method.`);
+    }
 
-    if (definition.methodName === 'error') {
-        return [
-            `{ ...(${getNodeText(sourceFile, optionsExpression)}), ...${injectedOptions} }`,
-            getNodeText(sourceFile, renderArg),
-        ];
+    const normalizedMethod = methodName === '*' ? 'all' : methodName.toLowerCase();
+    if (!serverRouteMethods.has(normalizedMethod)) {
+        throw new Error(`defineServerRoute(...) in ${sourceFile.fileName} uses unsupported method "${methodName}".`);
     }
 
-    const { dataArg } = getClientRouteSignature(sourceFile, definition);
     return [
-        `{ ...(${getNodeText(sourceFile, optionsExpression)}), ...${injectedOptions} }`,
-        getNodeText(sourceFile, dataArg!),
-        getNodeText(sourceFile, renderArg),
+        {
+            methodName: normalizedMethod,
+            sourceLocation,
+            targetExpression: pathExpression,
+            optionsExpression,
+            optionsArg,
+            hasData: false,
+        },
     ];
 };
 
-const buildServerRegisterArgs = (sourceFile: ts.SourceFile, definition: TRouteDefinition) => {
-    const sourceLocation = getNodeLocation(sourceFile, definition.callExpression);
-    const [targetArg, ...routeArgs] = [...definition.args];
-    const controllerArg = routeArgs[routeArgs.length - 1];
-    const optionsArg =
-        routeArgs.length >= 2 && ts.isObjectLiteralExpression(routeArgs[0]) ? routeArgs[0] : undefined;
-    const injectedOptions = buildInjectedRouteMetadata(sourceFile.fileName, sourceLocation);
+const collectExplicitRouteDefinitions = (sourceFile: ts.SourceFile, side: TRouteSide) => {
+    assertNoLegacyRouteMagic(sourceFile, side);
 
-    if (routeArgs.length === 1) {
-        return [getNodeText(sourceFile, targetArg), injectedOptions, getNodeText(sourceFile, controllerArg)];
+    const definitionExpression = getDefaultRouteDefinitionExpression(sourceFile);
+    if (!definitionExpression) {
+        throw new Error(`No route definition export was found in ${sourceFile.fileName}. Expected export default define*Route(...).`);
     }
 
-    if (optionsArg) {
-        return [
-            getNodeText(sourceFile, targetArg),
-            `{ ...(${getNodeText(sourceFile, optionsArg)}), ...${injectedOptions} }`,
-            getNodeText(sourceFile, controllerArg),
-        ];
-    }
-
-    return [getNodeText(sourceFile, targetArg), ...routeArgs.map((arg) => getNodeText(sourceFile, arg))];
+    return parseExplicitRouteCall(sourceFile, side, definitionExpression);
 };
 
-const buildRegisterStatements = (
-    sourceFile: ts.SourceFile,
-    side: TRouteSide,
-    definitions: TRouteDefinition[],
-    clientRoute?: TGeneratedClientRouteModuleOptions,
-) => {
-    if (side === 'client') {
-        if (!clientRoute) {
-            throw new Error(`Missing client route metadata for ${sourceFile.fileName}.`);
-        }
+const getRouteOptionMetadata = (node: ts.ObjectLiteralExpression | undefined) => {
+    const optionKeys = node ? getObjectLiteralPropertyKeys(node) : [];
+    const normalizedOptionKeys: string[] = [];
+    const invalidOptionKeys: string[] = [];
+    const reservedOptionKeys: string[] = [];
 
-        if (definitions.length !== 1) {
-            throw new Error(
-                `Frontend route definition files can contain only one route definition. ${definitions.length} were found in ${sourceFile.fileName}.`,
-            );
-        }
+    for (const optionKey of optionKeys) {
+        try {
+            const normalizedOptionKey = getRouteOptionKey(optionKey);
 
-        const definition = definitions[0];
-        const [routePath, ...routeArgs] = [...definition.args];
-        const finalArgs = [
-            getNodeText(sourceFile, routePath),
-            ...buildClientRegisterArgs(sourceFile, definition, clientRoute),
-        ];
+            if (normalizedOptionKey) {
+                normalizedOptionKeys.push(normalizedOptionKey);
+                continue;
+            }
 
-        return [`return ${definition.serviceLocalName}.${definition.methodName}(${finalArgs.join(', ')});`];
+            invalidOptionKeys.push(optionKey);
+        } catch (error) {
+            reservedOptionKeys.push(optionKey);
+        }
     }
 
-    return definitions.map((definition) => {
-        const args = buildServerRegisterArgs(sourceFile, definition);
-
-        return `${definition.serviceLocalName}.${definition.methodName}(${args.join(', ')});`;
-    });
+    return { optionKeys, normalizedOptionKeys, invalidOptionKeys, reservedOptionKeys };
 };
 
+const buildInjectedRouteMetadata = (sourceFilepath: string, sourceLocation: TIndexedSourceLocation, extra: string[] = []) =>
+    `{ filepath: ${JSON.stringify(normalizeFilepath(sourceFilepath))}, sourceLocation: { line: ${sourceLocation.line}, column: ${sourceLocation.column} }${extra.length > 0 ? `, ${extra.join(', ')}` : ''} }`;
+
+const normalizeRelativeImportPath = (value: string) => (value.startsWith('.') ? value : `./${value}`);
+
 export const getGeneratedRouteModuleFilepath = (generatedRoot: string, sourceRoot: string, sourceFilepath: string) =>
     path.join(generatedRoot, 'route-modules', path.relative(sourceRoot, sourceFilepath));
 
+const getSourceImportPath = (outputFilepath: string, sourceFilepath: string) =>
+    normalizeRelativeImportPath(path.relative(path.dirname(outputFilepath), sourceFilepath).replace(/\\/g, '/')).replace(
+        /\.(ts|tsx|js|jsx)$/,
+        '',
+    );
+
 export const indexRouteDefinitions = ({ side, sourceFilepath }: { side: TRouteSide; sourceFilepath: string }) => {
     const code = fs.readFileSync(sourceFilepath, 'utf8');
     const sourceFile = parseSourceFile(sourceFilepath, code);
-    const stripRanges: Array<{ start: number; end: number }> = [];
-    const importedServices = collectImportedServices(sourceFile, side, stripRanges);
-    const definitions = collectRouteDefinitions(sourceFile, importedServices, stripRanges);
+    const definitions = collectExplicitRouteDefinitions(sourceFile, side);
     const staticBindings = collectStaticBindings(sourceFile);
+    const staticBindingInitializers = collectStaticBindingInitializers(sourceFile);
 
     if (definitions.length === 0) {
         throw new Error(`No route definitions were found in ${sourceFilepath}.`);
@@ -573,85 +647,96 @@ export const indexRouteDefinitions = ({ side, sourceFilepath }: { side: TRouteSi
     }
 
     return definitions.map<TIndexedRouteDefinition>((definition) => {
-        const sourceLocation = getNodeLocation(sourceFile, definition.callExpression);
-        const resolveStaticValue = (node: ts.Expression) => tryEvaluateStaticExpression(node, new Map(), staticBindings);
+        const sourceLocation = definition.sourceLocation;
+        const resolveStaticValue = (node: ts.Expression) =>
+            tryEvaluateStaticExpression(node, staticBindingInitializers, staticBindings);
 
         if (side === 'client') {
-            const targetArg = definition.args[0];
-            const clientSignature = getClientRouteSignature(sourceFile, definition);
-            const optionMetadata = getRouteOptionMetadata(clientSignature.optionsArg);
+            const targetArg = definition.targetExpression;
+            const optionMetadata = getRouteOptionMetadata(definition.optionsArg);
             const resolvedStaticValue = resolveStaticValue(targetArg);
 
             return definition.methodName === 'error'
-                ? {
-                      methodName: definition.methodName,
-                      serviceLocalName: definition.serviceLocalName,
-                      sourceLocation,
-                      targetResolution:
-                          getLiteralNumberValue(targetArg) !== undefined
-                              ? 'literal'
-                              : typeof resolvedStaticValue === 'number'
-                                ? 'static-expression'
-                                : 'dynamic-expression',
-                      code:
-                          getLiteralNumberValue(targetArg) ??
-                          (typeof resolvedStaticValue === 'number' ? resolvedStaticValue : undefined),
-                      codeRaw: getNodeText(sourceFile, targetArg),
-                      optionKeys: optionMetadata.optionKeys,
-                      normalizedOptionKeys: optionMetadata.normalizedOptionKeys,
-                      invalidOptionKeys: optionMetadata.invalidOptionKeys,
-                      reservedOptionKeys: optionMetadata.reservedOptionKeys,
-                      optionsRaw: getNodeText(sourceFile, clientSignature.optionsExpression),
-                      hasData: false,
-                  }
-                : {
-                      methodName: definition.methodName,
-                      serviceLocalName: definition.serviceLocalName,
-                      sourceLocation,
-                      targetResolution:
-                          getLiteralStringValue(targetArg) !== undefined
-                              ? 'literal'
-                              : typeof resolvedStaticValue === 'string'
-                                ? 'static-expression'
-                                : 'dynamic-expression',
-                      path:
-                          getLiteralStringValue(targetArg) ??
-                          (typeof resolvedStaticValue === 'string' ? resolvedStaticValue : undefined),
-                      pathRaw: getNodeText(sourceFile, targetArg),
-                      optionKeys: optionMetadata.optionKeys,
-                      normalizedOptionKeys: optionMetadata.normalizedOptionKeys,
-                      invalidOptionKeys: optionMetadata.invalidOptionKeys,
-                      reservedOptionKeys: optionMetadata.reservedOptionKeys,
-                      optionsRaw: getNodeText(sourceFile, clientSignature.optionsExpression),
-                      hasData: clientSignature.hasData,
-                  };
+                ? (() => {
+                      const literalCode = getLiteralNumberValue(targetArg);
+                      const code = literalCode ?? (typeof resolvedStaticValue === 'number' ? resolvedStaticValue : undefined);
+
+                      if (code === undefined) {
+                          const location = getNodeLocation(sourceFile, targetArg);
+                          throw new Error(
+                              `${sourceFile.fileName}:${location.line}:${location.column} defineErrorRoute code must resolve to a number.`,
+                          );
+                      }
+
+                      return {
+                          methodName: definition.methodName,
+                          serviceLocalName: 'Router',
+                          sourceLocation,
+                          targetResolution: literalCode !== undefined ? 'literal' : 'static-expression',
+                          code,
+                          codeRaw: getNodeText(sourceFile, targetArg),
+                          optionKeys: optionMetadata.optionKeys,
+                          normalizedOptionKeys: optionMetadata.normalizedOptionKeys,
+                          invalidOptionKeys: optionMetadata.invalidOptionKeys,
+                          reservedOptionKeys: optionMetadata.reservedOptionKeys,
+                          optionsRaw: definition.optionsExpression ? getNodeText(sourceFile, definition.optionsExpression) : undefined,
+                          hasData: false,
+                      };
+                  })()
+                : (() => {
+                      const literalPath = getLiteralStringValue(targetArg);
+                      const routePath = literalPath ?? (typeof resolvedStaticValue === 'string' ? resolvedStaticValue : undefined);
+
+                      if (routePath === undefined) {
+                          const location = getNodeLocation(sourceFile, targetArg);
+                          throw new Error(
+                              `${sourceFile.fileName}:${location.line}:${location.column} definePageRoute path must resolve to a string.`,
+                          );
+                      }
+
+                      return {
+                          methodName: definition.methodName,
+                          serviceLocalName: 'Router',
+                          sourceLocation,
+                          targetResolution: literalPath !== undefined ? 'literal' : 'static-expression',
+                          path: routePath,
+                          pathRaw: getNodeText(sourceFile, targetArg),
+                          optionKeys: optionMetadata.optionKeys,
+                          normalizedOptionKeys: optionMetadata.normalizedOptionKeys,
+                          invalidOptionKeys: optionMetadata.invalidOptionKeys,
+                          reservedOptionKeys: optionMetadata.reservedOptionKeys,
+                          optionsRaw: definition.optionsExpression ? getNodeText(sourceFile, definition.optionsExpression) : undefined,
+                          hasData: definition.hasData,
+                      };
+                  })();
         }
 
-        const targetArg = definition.args[0];
-        const optionsArg =
-            definition.args.length >= 3 && ts.isObjectLiteralExpression(definition.args[1])
-                ? definition.args[1]
-                : undefined;
-        const optionMetadata = getRouteOptionMetadata(optionsArg);
+        const targetArg = definition.targetExpression;
+        const optionMetadata = getRouteOptionMetadata(definition.optionsArg);
         const resolvedPath = getLiteralStringValue(targetArg) ?? resolveStaticValue(targetArg);
 
+        if (typeof resolvedPath !== 'string') {
+            const location = getNodeLocation(sourceFile, targetArg);
+            throw new Error(
+                `${sourceFile.fileName}:${location.line}:${location.column} defineServerRoute path must resolve to a string.`,
+            );
+        }
+
         return {
             methodName: definition.methodName,
-            serviceLocalName: definition.serviceLocalName,
+            serviceLocalName: 'Router',
             sourceLocation,
             targetResolution:
                 getLiteralStringValue(targetArg) !== undefined
                     ? 'literal'
-                    : typeof resolvedPath === 'string'
-                      ? 'static-expression'
-                      : 'dynamic-expression',
-            path: typeof resolvedPath === 'string' ? resolvedPath : undefined,
+                    : 'static-expression',
+            path: resolvedPath,
             pathRaw: getNodeText(sourceFile, targetArg),
             optionKeys: optionMetadata.optionKeys,
             normalizedOptionKeys: optionMetadata.normalizedOptionKeys,
             invalidOptionKeys: optionMetadata.invalidOptionKeys,
             reservedOptionKeys: optionMetadata.reservedOptionKeys,
-            optionsRaw: optionsArg ? getNodeText(sourceFile, optionsArg) : undefined,
+            optionsRaw: definition.optionsExpression ? getNodeText(sourceFile, definition.optionsExpression) : undefined,
             hasData: false,
         };
     });
@@ -663,26 +748,22 @@ export const writeGeneratedRouteModule = ({
     side,
     sourceFilepath,
     clientRoute,
-    routeSourceFilepaths,
 }: TWriteGeneratedRouteModuleOptions) => {
     const code = fs.readFileSync(sourceFilepath, 'utf8');
     const sourceFile = parseSourceFile(sourceFilepath, code);
-    const stripRanges: Array<{ start: number; end: number }> = [];
-    const importedServices = collectImportedServices(sourceFile, side, stripRanges);
-    collectNestedRouteImports(sourceFile, sourceFilepath, routeSourceFilepaths, stripRanges);
-    const definitions = collectRouteDefinitions(sourceFile, importedServices, stripRanges);
+    const definitions = collectExplicitRouteDefinitions(sourceFile, side);
 
     if (definitions.length === 0) {
         throw new Error(`No route definitions were found in ${sourceFilepath}.`);
     }
 
-    const remainingSource = rebaseRelativeModuleSpecifiers(
-        buildRemainingSource(sourceFile, stripRanges),
-        outputFilepath,
-        sourceFilepath,
-    );
-    const registerStatements = buildRegisterStatements(sourceFile, side, definitions, clientRoute);
     const runtimeAppImportPath = runtime === 'client' ? '@/client/index' : '@/server/index';
+    const sourceImportPath = getSourceImportPath(outputFilepath, sourceFilepath);
+    const metadataEntries = definitions.map((definition) => {
+        const extra = side === 'client' && clientRoute ? [`id: ${JSON.stringify(clientRoute.chunkId)}`] : [];
+
+        return buildInjectedRouteMetadata(sourceFilepath, definition.sourceLocation, extra);
+    });
 
     const content = `/*----------------------------------
 - GENERATED FILE
@@ -691,12 +772,25 @@ export const writeGeneratedRouteModule = ({
 // This file is generated by Proteum from ${path.relative(process.cwd(), sourceFilepath).replace(/\\/g, '/')}.
 // Do not edit it manually.
 
-import type __GeneratedRouteApp from ${JSON.stringify(runtimeAppImportPath)};
-
-${remainingSource}
-${remainingSource ? '\n' : ''}export const __register = (app: __GeneratedRouteApp) => {
-  ${buildDestructuring(importedServices)}
-  ${registerStatements.join('\n  ')}
+import type __GeneratedRouteAppExport from ${JSON.stringify(runtimeAppImportPath)};
+import __routeDefinition from ${JSON.stringify(sourceImportPath)};
+import { normalizeRouteDefinitions, registerRouteDefinition } from '@common/router/definitions';
+
+type __GeneratedRouteApp = __GeneratedRouteAppExport extends abstract new (...args: any[]) => infer __GeneratedRouteAppInstance
+  ? __GeneratedRouteAppInstance
+  : __GeneratedRouteAppExport;
+
+const __routeMetadata = [
+  ${metadataEntries.join(',\n  ')}
+];
+
+export const __register = (app: __GeneratedRouteApp) => {
+  const __definitions = normalizeRouteDefinitions(__routeDefinition as any, app as any);
+  let __registeredRoute;
+  for (let __index = 0; __index < __definitions.length; __index += 1) {
+    __registeredRoute = registerRouteDefinition(app.Router as any, __definitions[__index] as any, __routeMetadata[__index]);
+  }
+  return __registeredRoute;
 };
 `;