proteum 2.0.0 → 2.1.0

package/cli/compiler/artifacts/controllers.ts

@@ -0,0 +1,150 @@
+import path from 'path';
+
+import app from '../../app';
+import cli from '../..';
+import { generateControllerClientTree, indexControllers, printControllerTree } from '../common/controllers';
+import { TProteumManifestController } from '../common/proteumManifest';
+import writeIfChanged from '../writeIfChanged';
+import { normalizeAbsolutePath } from './shared';
+
+const getManifestScopeFromImportPath = (importPath: string) =>
+    importPath.startsWith('@server/controllers/') ? 'framework' : 'app';
+
+export const generateControllerArtifacts = () => {
+    const controllers = indexControllers([
+        { importPrefix: '@server/controllers/', root: path.join(cli.paths.core.root, 'server', 'controllers') },
+        { importPrefix: '@/server/controllers/', root: path.join(app.paths.root, 'server', 'controllers') },
+    ]);
+    const manifestControllers = controllers.flatMap<TProteumManifestController>((controller) =>
+        controller.methods.map((method) => ({
+            className: controller.className,
+            importPath: controller.importPath,
+            filepath: normalizeAbsolutePath(controller.filepath),
+            sourceLocation: method.sourceLocation,
+            routeBasePath: controller.routeBasePath,
+            methodName: method.name,
+            inputCallsCount: method.inputCallsCount,
+            hasInput: method.inputCallsCount > 0,
+            routePath: method.routePath,
+            httpPath: '/api/' + method.routePath,
+            clientAccessor: method.routePath.split('/').join('.'),
+            scope: getManifestScopeFromImportPath(controller.importPath),
+        })),
+    );
+    const clientTree = generateControllerClientTree(controllers);
+
+    const getControllerLeafMeta = (leaf: string) => {
+        const meta = JSON.parse(leaf) as {
+            routePath: string;
+            importPath: string;
+            className: string;
+            methodName: string;
+            hasInput: boolean;
+        };
+        const controllerIndex = controllers.findIndex((controller) => controller.importPath === meta.importPath);
+
+        if (controllerIndex === -1) {
+            throw new Error(`Unable to find controller import ${meta.importPath} while generating controller types.`);
+        }
+
+        return { ...meta, controllerIndex };
+    };
+
+    const runtimeLeaf = (leaf: string) => {
+        const meta = getControllerLeafMeta(leaf);
+        const resultType = `TControllerResult<Controller${meta.controllerIndex}, ${JSON.stringify(meta.methodName)}>`;
+
+        return meta.hasInput
+            ? `(data) => api.createFetcher<${resultType}>('POST', ${JSON.stringify(meta.routePath)}, data)`
+            : `() => api.createFetcher<${resultType}>('POST', ${JSON.stringify(meta.routePath)})`;
+    };
+
+    const typeImports = controllers
+        .map((controller, index) => `import type Controller${index} from ${JSON.stringify(controller.importPath)};`)
+        .join('\n');
+
+    const typeLeaf = (leaf: string) => {
+        const meta = getControllerLeafMeta(leaf);
+        const fetcherType = `TControllerFetcher<Controller${meta.controllerIndex}, ${JSON.stringify(meta.methodName)}>`;
+
+        return meta.hasInput ? `(data: any) => ${fetcherType}` : `() => ${fetcherType}`;
+    };
+
+    const createControllersContent = `/*----------------------------------
+- GENERATED FILE
+----------------------------------*/
+
+// This file is generated by Proteum from server controller files.
+// Do not edit it manually.
+
+import type ApiClient from '@common/router/request/api';
+import type { TFetcher } from '@common/router/request/api';
+${typeImports ? '\n' + typeImports : ''}
+
+type TControllerResult<TController, TMethod extends keyof TController> =
+    TController[TMethod] extends (...args: any[]) => infer TResult ? Awaited<TResult> : never;
+
+type TControllerFetcher<TController, TMethod extends keyof TController> = TFetcher<TControllerResult<TController, TMethod>>;
+
+export type TControllers = ${printControllerTree(clientTree, typeLeaf)};
+
+export const createControllers = (
+    api: Pick<ApiClient, 'createFetcher'>
+): TControllers => (
+${printControllerTree(clientTree, runtimeLeaf)}
+);
+
+export default createControllers;
+`;
+
+    writeIfChanged(path.join(app.paths.common.generated, 'controllers.ts'), createControllersContent);
+
+    writeIfChanged(
+        path.join(app.paths.client.generated, 'controllers.ts'),
+        `export { createControllers, default } from '@generated/common/controllers';
+export type { TControllers } from '@generated/common/controllers';
+`,
+    );
+
+    const controllerImports = controllers
+        .map((controller, index) => `import Controller${index} from ${JSON.stringify(controller.importPath)};`)
+        .join('\n');
+
+    const controllerEntries = controllers.flatMap((controller, controllerIndex) =>
+        controller.methods.map(
+            (method) => `    {
+        path: ${JSON.stringify('/api/' + method.routePath)},
+        Controller: Controller${controllerIndex},
+        method: ${JSON.stringify(method.name)},
+    },`,
+        ),
+    );
+
+    writeIfChanged(
+        path.join(app.paths.server.generated, 'controllers.ts'),
+        `/*----------------------------------
+- GENERATED FILE
+----------------------------------*/
+
+// This file is generated by Proteum from server controller files.
+// Do not edit it manually.
+
+import type Controller from '@server/app/controller';
+${controllerImports ? '\n' + controllerImports : ''}
+
+export type TGeneratedControllerDefinition = {
+    path: string,
+    Controller: new (request: any) => Controller,
+    method: string,
+}
+
+const controllers: TGeneratedControllerDefinition[] = [
+${controllerEntries.join('\n')}
+];
+
+export default controllers;
+`,
+    );
+
+    return manifestControllers;
+};

package/cli/compiler/artifacts/discovery.ts

@@ -0,0 +1,132 @@
+import path from 'path';
+import fs from 'fs-extra';
+import ts from 'typescript';
+
+import app from '../../app';
+import { normalizePath } from './shared';
+
+const ignoredServiceDirectories = new Set(['node_modules', 'proteum']);
+
+export const findServiceDirectories = (dir: string): string[] => {
+    if (!fs.existsSync(dir)) return [];
+
+    const directories: string[] = [];
+
+    for (const dirent of fs.readdirSync(dir, { withFileTypes: true })) {
+        const filePath = path.resolve(dir, dirent.name);
+
+        if (ignoredServiceDirectories.has(dirent.name)) continue;
+
+        let shouldTraverse = false;
+
+        if (dirent.isSymbolicLink()) {
+            const realPath = path.resolve(dir, fs.readlinkSync(filePath));
+            shouldTraverse = fs.lstatSync(realPath).isDirectory();
+        } else if (dirent.isDirectory()) {
+            shouldTraverse = true;
+        }
+
+        if (shouldTraverse) {
+            directories.push(...findServiceDirectories(filePath));
+            continue;
+        }
+
+        if (dirent.name === 'service.json') {
+            directories.push(path.dirname(filePath));
+        }
+    }
+
+    return directories;
+};
+
+const hasRegisteredRouteDefinitions = (filepath: string, content: string) => {
+    const sourceFile = ts.createSourceFile(
+        filepath,
+        content,
+        ts.ScriptTarget.Latest,
+        true,
+        filepath.endsWith('.tsx') ? ts.ScriptKind.TSX : ts.ScriptKind.TS,
+    );
+
+    return sourceFile.statements.some((statement) => {
+        if (!ts.isExpressionStatement(statement)) return false;
+        if (!ts.isCallExpression(statement.expression)) return false;
+        if (!ts.isPropertyAccessExpression(statement.expression.expression)) return false;
+
+        const callee = statement.expression.expression;
+
+        return (
+            ts.isIdentifier(callee.expression) &&
+            callee.expression.text === 'Router' &&
+            ['page', 'error', 'get', 'post', 'put', 'delete', 'patch'].includes(callee.name.text)
+        );
+    });
+};
+
+const findRegisteredRouteFiles = (dir: string, options: { excludeLayoutDirectories?: boolean } = {}): string[] => {
+    if (!fs.existsSync(dir)) return [];
+
+    const files: string[] = [];
+
+    for (const dirent of fs.readdirSync(dir, { withFileTypes: true })) {
+        const filePath = path.join(dir, dirent.name);
+
+        if (dirent.isDirectory()) {
+            if (options.excludeLayoutDirectories && dirent.name === '_layout') continue;
+
+            files.push(...findRegisteredRouteFiles(filePath, options));
+            continue;
+        }
+
+        if (!dirent.isFile()) continue;
+        if (!/\.(ts|tsx)$/.test(dirent.name)) continue;
+
+        const content = fs.readFileSync(filePath, 'utf8');
+        if (!hasRegisteredRouteDefinitions(filePath, content)) continue;
+
+        files.push(filePath);
+    }
+
+    return files;
+};
+
+export const findClientRouteFiles = (dir: string) => findRegisteredRouteFiles(dir, { excludeLayoutDirectories: true });
+
+export const findServerRouteFiles = (dir: string) => findRegisteredRouteFiles(dir);
+
+export const findLayoutFiles = (dir: string): string[] => {
+    if (!fs.existsSync(dir)) return [];
+
+    const files: string[] = [];
+
+    for (const dirent of fs.readdirSync(dir, { withFileTypes: true })) {
+        const filePath = path.join(dir, dirent.name);
+
+        if (dirent.isDirectory()) {
+            files.push(...findLayoutFiles(filePath));
+            continue;
+        }
+
+        if (!dirent.isFile()) continue;
+        if (dirent.name !== 'index.tsx') continue;
+        if (!normalizePath(filePath).includes('/_layout/')) continue;
+
+        files.push(filePath);
+    }
+
+    return files;
+};
+
+export const readPreloadedRouteChunks = () => {
+    const preloadPath = path.join(app.paths.pages, 'preload.json');
+
+    if (!fs.existsSync(preloadPath)) return new Set<string>();
+
+    const content = fs.readJsonSync(preloadPath);
+
+    if (!Array.isArray(content)) {
+        throw new Error(`Invalid client/pages/preload.json format: expected an array of chunk ids.`);
+    }
+
+    return new Set<string>(content.filter((value): value is string => typeof value === 'string'));
+};

package/cli/compiler/artifacts/manifest.ts

@@ -0,0 +1,267 @@
+import path from 'path';
+import fs from 'fs-extra';
+import yaml from 'yaml';
+
+import app from '../../app';
+import cli from '../..';
+import { reservedRouteSetupKeys, routeSetupOptionKeys } from '../../../common/router/pageSetup';
+import {
+    TProteumManifest,
+    TProteumManifestController,
+    TProteumManifestDiagnostic,
+    TProteumManifestLayout,
+    TProteumManifestRoute,
+} from '../common/proteumManifest';
+import { writeProteumManifest } from '../common/proteumManifest';
+import { normalizeAbsolutePath, normalizePath } from './shared';
+
+const envRequiredTopLevelKeys = ['name', 'profile', 'router', 'console'];
+
+const getEnvTopLevelKeys = () => {
+    const envFilepath = path.join(app.paths.root, 'env.yaml');
+
+    if (!fs.existsSync(envFilepath)) return [];
+
+    const rawEnv = yaml.parse(fs.readFileSync(envFilepath, 'utf8'));
+
+    if (!rawEnv || typeof rawEnv !== 'object' || Array.isArray(rawEnv)) return [];
+
+    return Object.keys(rawEnv).sort((a, b) => a.localeCompare(b));
+};
+
+const collectManifestDiagnostics = ({
+    controllers,
+    routes,
+}: {
+    controllers: TProteumManifestController[];
+    routes: TProteumManifest['routes'];
+}) => {
+    const diagnostics: TProteumManifestDiagnostic[] = [];
+
+    const pushDiagnostic = (diagnostic: TProteumManifestDiagnostic) => {
+        diagnostics.push(diagnostic);
+    };
+
+    const createDuplicateDiagnostics = <
+        TEntry extends { filepath: string; sourceLocation?: { line: number; column: number } },
+    >(
+        entries: TEntry[],
+        {
+            code,
+            level,
+            message,
+        }: {
+            code: string;
+            level: TProteumManifestDiagnostic['level'];
+            message: (entry: TEntry, others: TEntry[]) => string;
+        },
+    ) => {
+        if (entries.length < 2) return;
+
+        for (const entry of entries) {
+            pushDiagnostic({
+                level,
+                code,
+                message: message(
+                    entry,
+                    entries.filter((candidate) => candidate !== entry),
+                ),
+                filepath: entry.filepath,
+                sourceLocation: entry.sourceLocation,
+                relatedFilepaths: entries.filter((candidate) => candidate !== entry).map((candidate) => candidate.filepath),
+            });
+        }
+    };
+
+    const trackDuplicates = <TEntry extends { filepath: string; sourceLocation?: { line: number; column: number } }>(
+        entries: TEntry[],
+        getKey: (entry: TEntry) => string | undefined,
+        config: {
+            code: string;
+            level: TProteumManifestDiagnostic['level'];
+            message: (entry: TEntry, others: TEntry[]) => string;
+        },
+    ) => {
+        const groups = new Map<string, TEntry[]>();
+
+        for (const entry of entries) {
+            const key = getKey(entry);
+            if (!key) continue;
+
+            const group = groups.get(key) || [];
+            group.push(entry);
+            groups.set(key, group);
+        }
+
+        for (const group of groups.values()) {
+            createDuplicateDiagnostics(group, config);
+        }
+    };
+
+    for (const route of [...routes.client, ...routes.server]) {
+        if (route.targetResolution === 'dynamic-expression') {
+            pushDiagnostic({
+                level: 'warning',
+                code: 'route.dynamic-target',
+                message:
+                    route.kind === 'client-error'
+                        ? `Proteum could not resolve this error code statically. Prefer a numeric literal or a const-only expression.`
+                        : `Proteum could not resolve this route path statically. Prefer a string literal or a const-only expression.`,
+                filepath: route.filepath,
+                sourceLocation: route.sourceLocation,
+            });
+        }
+
+        for (const optionKey of route.invalidOptionKeys) {
+            pushDiagnostic({
+                level: 'error',
+                code: 'route.invalid-option-key',
+                message: `"${optionKey}" is not a supported Router option key.`,
+                filepath: route.filepath,
+                sourceLocation: route.sourceLocation,
+            });
+        }
+
+        for (const optionKey of route.reservedOptionKeys) {
+            pushDiagnostic({
+                level: 'error',
+                code: 'route.reserved-option-key',
+                message: `"${optionKey}" is a reserved Router option key and cannot be set explicitly.`,
+                filepath: route.filepath,
+                sourceLocation: route.sourceLocation,
+            });
+        }
+    }
+
+    trackDuplicates(routes.client.filter((route) => route.kind === 'client-page'), (route) => route.path, {
+        code: 'route.duplicate-client-path',
+        level: 'warning',
+        message: (route, others) =>
+            `Duplicate client page path "${(route as TProteumManifestRoute).path}" also registered in ${others
+                .map((other) => normalizePath(path.relative(app.paths.root, other.filepath)))
+                .join(', ')}.`,
+    });
+
+    trackDuplicates(
+        routes.client.filter((route) => route.kind === 'client-error'),
+        (route) => (typeof route.code === 'number' ? String(route.code) : undefined),
+        {
+            code: 'route.duplicate-client-error',
+            level: 'warning',
+            message: (route, others) =>
+                `Duplicate client error code "${(route as TProteumManifestRoute).code}" also registered in ${others
+                    .map((other) => normalizePath(path.relative(app.paths.root, other.filepath)))
+                    .join(', ')}.`,
+        },
+    );
+
+    trackDuplicates(
+        routes.server,
+        (route) => (route.path ? `${route.methodName}:${route.path}` : undefined),
+        {
+            code: 'route.duplicate-server-route',
+            level: 'warning',
+            message: (route, others) =>
+                `Duplicate server route "${(route as TProteumManifestRoute).methodName.toUpperCase()} ${(route as TProteumManifestRoute).path}" also registered in ${others
+                    .map((other) => normalizePath(path.relative(app.paths.root, other.filepath)))
+                    .join(', ')}.`,
+        },
+    );
+
+    trackDuplicates(controllers, (controller) => controller.clientAccessor, {
+        code: 'controller.duplicate-client-accessor',
+        level: 'error',
+        message: (controller, others) =>
+            `Duplicate controller accessor "${controller.clientAccessor}" also registered in ${others
+                .map((other) => normalizePath(path.relative(app.paths.root, other.filepath)))
+                .join(', ')}.`,
+    });
+
+    trackDuplicates(controllers, (controller) => controller.httpPath, {
+        code: 'controller.duplicate-http-path',
+        level: 'error',
+        message: (controller, others) =>
+            `Duplicate controller HTTP path "${controller.httpPath}" also registered in ${others
+                .map((other) => normalizePath(path.relative(app.paths.root, other.filepath)))
+                .join(', ')}.`,
+    });
+
+    const postServerRoutesByPath = new Map(
+        routes.server
+            .filter((route) => route.methodName === 'post' && !!route.path)
+            .map((route) => [route.path as string, route]),
+    );
+
+    for (const controller of controllers) {
+        const matchingRoute = postServerRoutesByPath.get(controller.httpPath);
+
+        if (!matchingRoute) continue;
+
+        pushDiagnostic({
+            level: 'error',
+            code: 'controller.server-route-collision',
+            message: `Controller path "${controller.httpPath}" collides with an explicit POST server route.`,
+            filepath: controller.filepath,
+            sourceLocation: controller.sourceLocation,
+            relatedFilepaths: [matchingRoute.filepath],
+        });
+    }
+
+    return diagnostics.sort((a, b) => {
+        if (a.level !== b.level) return a.level === 'error' ? -1 : 1;
+        if (a.filepath !== b.filepath) return a.filepath.localeCompare(b.filepath);
+        if ((a.sourceLocation?.line || 0) !== (b.sourceLocation?.line || 0)) {
+            return (a.sourceLocation?.line || 0) - (b.sourceLocation?.line || 0);
+        }
+        return a.code.localeCompare(b.code);
+    });
+};
+
+export const writeCurrentProteumManifest = ({
+    services,
+    controllers,
+    routes,
+    layouts,
+}: {
+    services: TProteumManifest['services'];
+    controllers: TProteumManifestController[];
+    routes: TProteumManifest['routes'];
+    layouts: TProteumManifestLayout[];
+}) => {
+    const manifest: TProteumManifest = {
+        version: 1,
+        app: {
+            root: normalizeAbsolutePath(app.paths.root),
+            coreRoot: normalizeAbsolutePath(cli.paths.core.root),
+            identityFilepath: normalizeAbsolutePath(path.join(app.paths.root, 'identity.yaml')),
+            identity: {
+                name: app.identity.name,
+                identifier: app.identity.identifier,
+                description: app.identity.description,
+                language: app.identity.language,
+                locale: app.identity.locale,
+                title: app.identity.web?.title,
+                titleSuffix: app.identity.web?.titleSuffix,
+                fullTitle: app.identity.web?.fullTitle,
+                webDescription: app.identity.web?.description,
+                version: app.identity.web?.version,
+            },
+        },
+        conventions: {
+            routeSetupOptionKeys: [...routeSetupOptionKeys],
+            reservedRouteSetupKeys: [...reservedRouteSetupKeys],
+        },
+        env: {
+            sourceFilepath: normalizeAbsolutePath(path.join(app.paths.root, 'env.yaml')),
+            loadedTopLevelKeys: getEnvTopLevelKeys(),
+            requiredTopLevelKeys: [...envRequiredTopLevelKeys],
+        },
+        services,
+        controllers,
+        routes,
+        layouts,
+        diagnostics: collectManifestDiagnostics({ controllers, routes }),
+    };
+
+    writeProteumManifest(app.paths.root, manifest);
+};