proteum 2.5.0 → 2.5.2

package/tests/definition-contracts.test.cjs

@@ -18,6 +18,7 @@ const {
     indexRouteDefinitions,
     writeGeneratedRouteModule,
 } = require('../cli/compiler/common/generatedRouteModules.ts');
+const { createTypedControllerHelperContent } = require('../cli/compiler/artifacts/controllerHelper.ts');
 const { findClientRouteFiles } = require('../cli/compiler/artifacts/discovery.ts');
 const { indexControllers } = require('../cli/compiler/common/controllers.ts');
 const {
@@ -107,6 +108,51 @@ export default definePageRoute({
     assert.deepEqual(definition.normalizedOptionKeys, ['auth']);
 });
 
+test('route indexer accepts imported const-only option metadata', () => {
+    const root = createTempDir();
+    const filepath = path.join(root, 'client/pages/feed.tsx');
+    const catalogFilepath = path.join(root, 'client/catalogs/routes.ts');
+
+    writeFile(
+        catalogFilepath,
+        `export const PAGE_AUTH = {
+    feed: {
+        auth: {
+            hasFeature: 'opportunitiesFreq',
+        },
+        authTracking: {
+            source: 'investor_feed',
+            feature: 'opportunitiesFreq',
+            action: 'open-feed',
+            triggerKind: 'open',
+        },
+    },
+} as const;
+`,
+    );
+    writeFile(
+        filepath,
+        `import { definePageRoute } from '@common/router/definitions';
+import { PAGE_AUTH } from '@/client/catalogs/routes';
+
+export default definePageRoute({
+    path: '/feed',
+    options: {
+        auth: PAGE_AUTH.feed.auth,
+        authTracking: PAGE_AUTH.feed.authTracking,
+    },
+    data: null,
+    render: () => null,
+});
+`,
+    );
+
+    const [definition] = indexRouteDefinitions({ side: 'client', sourceFilepath: filepath });
+
+    assert.equal(definition.path, '/feed');
+    assert.deepEqual(definition.normalizedOptionKeys, ['auth', 'authTracking']);
+});
+
 test('router port override updates absolute runtime URLs', () => {
     const root = createTempDir();
 
@@ -262,6 +308,37 @@ export default defineServerRoutes(({ Users }) => [
     assert.equal(definition.targetResolution, 'static-expression');
 });
 
+test('server route factories can push explicit route definitions from a block body', () => {
+    const root = createTempDir();
+    const filepath = path.join(root, 'server/routes/api.ts');
+
+    writeFile(
+        filepath,
+        `import { defineServerRoute, defineServerRoutes } from '@common/router/definitions';
+
+export default defineServerRoutes((app) => {
+    const { Users } = app;
+    const routeOptions = {};
+    const routes = [];
+
+    routes.push(defineServerRoute({
+        method: 'GET',
+        path: '/api/users',
+        options: routeOptions,
+        handler: async () => Users.list(),
+    }));
+
+    return routes;
+});
+`,
+    );
+
+    const [definition] = indexRouteDefinitions({ side: 'server', sourceFilepath: filepath });
+
+    assert.equal(definition.methodName, 'get');
+    assert.equal(definition.path, '/api/users');
+});
+
 test('route definitions register through explicit router registrar', () => {
     const calls = [];
 
@@ -386,6 +463,17 @@ export default class Legacy extends Controller {
     );
 });
 
+test('generated typed controller helper binds action context to app root', () => {
+    const content = createTypedControllerHelperContent('TestApp');
+
+    assert.match(content, /@server\/app\/controller/);
+    assert.match(content, /@\/server\/index/);
+    assert.match(content, /export type TApplication = import\('@\/server\/index'\)\.TestApp/);
+    assert.match(content, /export type TControllerRequestServices = import\('@\/server\/index'\)\.TControllerRequestServices/);
+    assert.match(content, /TControllerActionContext<\n    TInput,\n    TApplication,\n    TControllerRequestServices\n>/);
+    assert.match(content, /handler: \(context: TTypedControllerActionContext<z\.output<TSchema>>\) => TResult/);
+});
+
 test('service artifact parser reads defineApplication router factories', () => {
     const root = createTempDir();
     const filepath = path.join(root, 'server/index.ts');
@@ -451,3 +539,44 @@ export default App;
     assert.deepEqual(bootstrap.rootServices.map((service) => service.registeredName), ['Router']);
     assert.deepEqual(bootstrap.routerPlugins.map((service) => service.registeredName), ['schema']);
 });
+
+test('service artifact parser reads named defineApplication service factories', () => {
+    const root = createTempDir();
+    const filepath = path.join(root, 'server/index.ts');
+    const serviceFilepath = path.join(root, 'server/services/Billing.ts');
+    const { parseAppBootstrapSource } = loadServiceArtifactsForAppRoot(root);
+
+    writeFile(serviceFilepath, 'export default class Billing {}');
+    writeFile(
+        filepath,
+        `import { defineApplication } from '@server/app';
+import Router from '@server/services/router';
+import SchemaRouter from '@server/services/schema/router';
+import Billing from '@/server/services/Billing';
+
+const createServices = (app) => ({
+    Billing: new Billing(app, {}, app),
+});
+
+const createRouter = (app) => new Router(
+    app,
+    {
+        plugins: {
+            schema: new SchemaRouter({}, app),
+        },
+    },
+    app,
+);
+
+export default defineApplication({
+    services: createServices,
+    router: createRouter,
+});
+`,
+    );
+
+    const bootstrap = parseAppBootstrapSource(filepath);
+
+    assert.deepEqual(bootstrap.rootServices.map((service) => service.registeredName), ['Billing', 'Router']);
+    assert.deepEqual(bootstrap.routerPlugins.map((service) => service.registeredName), ['schema']);
+});

package/tests/dev-transpile-watch.test.cjs

@@ -377,8 +377,9 @@ import SchemaRouter from '@server/services/schema/router';
 import * as appConfig from '@/server/config/app';
 
 export default defineApplication({
-    services: (app) => ({
-        Router: new Router(
+    services: () => ({}),
+    router: (app) =>
+        new Router(
             app,
             {
                 ...appConfig.routerBaseConfig,
@@ -388,7 +389,6 @@ export default defineApplication({
             },
             app,
         ),
-    }),
 });
 `,
     );
@@ -405,9 +405,6 @@ export default class TranspileWatchClient extends ClientApplication {
 
     public boot() {}
     public handleUpdate() {}
-    public handleError(error: Error) {
-        throw error;
-    }
 }
 `,
     );

package/tests/eslint-rules.test.cjs

@@ -3,10 +3,10 @@ const { Linter } = require('eslint');
 
 const { createProteumEslintConfig } = require('../eslint.js');
 
-const lint = (code) => {
+const lint = (code, filename = 'client/example.tsx') => {
     const linter = new Linter({ configType: 'flat' });
     return linter.verify(code, createProteumEslintConfig(), {
-        filename: 'client/example.tsx',
+        filename,
     });
 };
 
@@ -102,7 +102,7 @@ test('proteum lint allows rethrowing the caught error', () => {
     assert.equal(messages.filter((message) => message.ruleId === swallowedErrorRuleId).length, 0);
 });
 
-test('proteum lint allows surfacing original error details', () => {
+test('proteum lint rejects user feedback that does not route the caught error', () => {
     const messages = lint(`
         export const run = async () => {
             try {
@@ -115,10 +115,10 @@ test('proteum lint allows surfacing original error details', () => {
         };
     `);
 
-    assert.equal(messages.filter((message) => message.ruleId === swallowedErrorRuleId).length, 0);
+    assert.equal(messages.some((message) => message.ruleId === swallowedErrorRuleId), true);
 });
 
-test('proteum lint allows surfacing a message derived from the caught error', () => {
+test('proteum lint rejects derived message state that does not route the caught error', () => {
     const messages = lint(`
         export const run = async () => {
             try {
@@ -130,10 +130,10 @@ test('proteum lint allows surfacing a message derived from the caught error', ()
         };
     `);
 
-    assert.equal(messages.filter((message) => message.ruleId === swallowedErrorRuleId).length, 0);
+    assert.equal(messages.some((message) => message.ruleId === swallowedErrorRuleId), true);
 });
 
-test('proteum lint allows routing promise failures to app error handling', () => {
+test('proteum lint allows client catches routed to context app error handling', () => {
     const messages = lint(`
         export const run = () => {
             const context = useContext();
@@ -145,3 +145,242 @@ test('proteum lint allows routing promise failures to app error handling', () =>
 
     assert.equal(messages.filter((message) => message.ruleId === swallowedErrorRuleId).length, 0);
 });
+
+test('proteum lint rejects optional client error handler calls', () => {
+    for (const statement of [
+        'app?.handleError(error);',
+        'context.app?.handleError(error);',
+        'window.app?.handleError(error);',
+    ]) {
+        const messages = lint(`
+            export const run = async () => {
+                const app = useContext();
+                const context = useContext();
+                try {
+                    await Investor.api.ensureApiKey();
+                } catch (error) {
+                    ${statement}
+                }
+            };
+        `);
+
+        assert.equal(messages.some((message) => message.ruleId === swallowedErrorRuleId), true);
+    }
+});
+
+test('proteum lint allows client catches using app error messages for UI feedback', () => {
+    const messages = lint(`
+        export const run = async () => {
+            const context = useContext();
+            try {
+                await Investor.api.ensureApiKey();
+            } catch (error) {
+                setError(context.app.handleError(error, 'Unable to finish this action.'));
+            }
+        };
+    `);
+
+    assert.equal(messages.filter((message) => message.ruleId === swallowedErrorRuleId).length, 0);
+});
+
+test('proteum lint allows client catches routed to local app error handling', () => {
+    const messages = lint(`
+        export const run = async () => {
+            const app = useContext();
+            try {
+                await Investor.api.ensureApiKey();
+            } catch (error) {
+                app.handleError(error);
+            }
+        };
+    `);
+
+    assert.equal(messages.filter((message) => message.ruleId === swallowedErrorRuleId).length, 0);
+});
+
+test('proteum lint allows client catches routed to useContext app error handling', () => {
+    const messages = lint(`
+        export const run = async () => {
+            try {
+                await Investor.api.ensureApiKey();
+            } catch (error) {
+                useContext().app.handleError(error);
+            }
+        };
+    `);
+
+    assert.equal(messages.filter((message) => message.ruleId === swallowedErrorRuleId).length, 0);
+});
+
+test('proteum lint rejects bare client error handlers', () => {
+    const messages = lint(`
+        export const run = async () => {
+            try {
+                await Investor.api.ensureApiKey();
+            } catch (error) {
+                handleError(error);
+            }
+        };
+    `);
+
+    assert.equal(messages.some((message) => message.ruleId === swallowedErrorRuleId), true);
+});
+
+test('proteum lint allows server catches routed to app error reporting', () => {
+    const messages = lint(
+        `
+            export const run = async (context) => {
+                try {
+                    await context.services.Worker.run();
+                } catch (error) {
+                    await context.app.reportError(error, context.request);
+                }
+            };
+        `,
+        'server/example.ts',
+    );
+
+    assert.equal(messages.filter((message) => message.ruleId === swallowedErrorRuleId).length, 0);
+});
+
+test('proteum lint allows server catches routed to instance app error reporting', () => {
+    const messages = lint(
+        `
+            export class WorkerController {
+                async run(context) {
+                    try {
+                        await context.services.Worker.run();
+                    } catch (error) {
+                        await this.app.reportError(error, context.request);
+                    }
+                }
+            }
+        `,
+        'server/example.ts',
+    );
+
+    assert.equal(messages.filter((message) => message.ruleId === swallowedErrorRuleId).length, 0);
+});
+
+test('proteum lint rejects optional server error reporter calls', () => {
+    for (const statement of [
+        'app.reportError?.(error);',
+        'app?.reportError(error);',
+        'context.app?.reportError(error);',
+    ]) {
+        const messages = lint(
+            `
+                export const run = async (context) => {
+                    const app = context.app;
+                    try {
+                        await context.services.Worker.run();
+                    } catch (error) {
+                        ${statement}
+                    }
+                };
+            `,
+            'server/example.ts',
+        );
+
+        assert.equal(messages.some((message) => message.ruleId === swallowedErrorRuleId), true);
+    }
+});
+
+test('proteum lint rejects conditional server error reporter calls', () => {
+    const messages = lint(
+        `
+            export const run = async (context) => {
+                const app = context.app;
+                try {
+                    await context.services.Worker.run();
+                } catch (error) {
+                    if (app) app.reportError(error, context.request);
+                }
+            };
+        `,
+        'server/example.ts',
+    );
+
+    assert.equal(messages.some((message) => message.ruleId === swallowedErrorRuleId), true);
+});
+
+test('proteum lint rejects server catches routed to client app error handling', () => {
+    const messages = lint(
+        `
+            export const run = async (context) => {
+                try {
+                    await context.services.Worker.run();
+                } catch (error) {
+                    context.app.handleError(error);
+                }
+            };
+        `,
+        'server/example.ts',
+    );
+
+    assert.equal(messages.some((message) => message.ruleId === swallowedErrorRuleId), true);
+});
+
+test('proteum lint rejects raw server error hooks as caught error handling', () => {
+    const messages = lint(
+        `
+            export const run = async (context) => {
+                try {
+                    await context.services.Worker.run();
+                } catch (error) {
+                    await context.app.runHook('error', error, context.request);
+                }
+            };
+        `,
+        'server/example.ts',
+    );
+
+    assert.equal(messages.some((message) => message.ruleId === swallowedErrorRuleId), true);
+});
+
+test('proteum lint allows manual promise rejection', () => {
+    const messages = lint(
+        `
+            export const run = (input) =>
+                new Promise((resolve, reject) => {
+                    input.load().catch((error) => {
+                        reject(error);
+                    });
+                });
+        `,
+        'common/example.ts',
+    );
+
+    assert.equal(messages.filter((message) => message.ruleId === swallowedErrorRuleId).length, 0);
+});
+
+test('proteum lint allows returning manual promise rejection', () => {
+    const messages = lint(
+        `
+            export const run = async (input) => {
+                try {
+                    await input.load();
+                } catch (error) {
+                    return Promise.reject(error);
+                }
+            };
+        `,
+        'common/example.ts',
+    );
+
+    assert.equal(messages.filter((message) => message.ruleId === swallowedErrorRuleId).length, 0);
+});
+
+test('proteum lint allows direct reject promise catch handlers', () => {
+    const messages = lint(
+        `
+            export const run = (input) =>
+                new Promise((resolve, reject) => {
+                    input.load().catch(reject);
+                });
+        `,
+        'common/example.ts',
+    );
+
+    assert.equal(messages.filter((message) => message.ruleId === swallowedErrorRuleId).length, 0);
+});

package/tests/scaffold-templates.test.cjs

@@ -0,0 +1,43 @@
+const assert = require('node:assert/strict');
+const path = require('node:path');
+
+const coreRoot = path.resolve(__dirname, '..');
+process.env.TS_NODE_PROJECT = path.join(coreRoot, 'cli', 'tsconfig.json');
+process.env.TS_NODE_TRANSPILE_ONLY = '1';
+require('ts-node/register/transpile-only');
+
+const { createCommandTemplate, createControllerTemplate, createServerIndexTemplate } = require('../cli/scaffold/templates.ts');
+
+test('server index scaffold uses explicit defineApplication router property', () => {
+    const content = createServerIndexTemplate({ appIdentifier: 'ExampleApp' });
+
+    assert.match(content, /const ExampleAppApplication = defineApplication\(\{/);
+    assert.match(content, /export type ExampleApp = InstanceType<typeof ExampleAppApplication>/);
+    assert.match(content, /export default ExampleAppApplication/);
+    assert.match(content, /export type TControllerRequestServices = \{\}/);
+    assert.match(content, /services: \(\) => \(\{\}\),/);
+    assert.match(content, /router: \(app\) =>\s+new Router\(/);
+    assert.doesNotMatch(content, /services: \(app\) => \(\{\s+Router: new Router\(/);
+});
+
+test('controller scaffold imports app-typed generated controller helpers', () => {
+    const content = createControllerTemplate({
+        appIdentifier: 'ExampleApp',
+        className: 'BillingController',
+        methodName: 'read',
+    });
+
+    assert.match(content, /from '@generated\/server\/controller'/);
+    assert.doesNotMatch(content, /from '@server\/app\/controller'/);
+});
+
+test('command scaffold infers app type from defineApplication default export', () => {
+    const content = createCommandTemplate({
+        className: 'BillingCommands',
+        methodName: 'sync',
+    });
+
+    assert.match(content, /import type AppApplication from '@\/server\/index'/);
+    assert.match(content, /type App = InstanceType<typeof AppApplication>/);
+    assert.doesNotMatch(content, /import type App from '@\/server\/index'/);
+});

package/tests/server-app-report-error.test.cjs

@@ -0,0 +1,135 @@
+const assert = require('node:assert/strict');
+const Module = require('node:module');
+const path = require('node:path');
+
+const coreRoot = path.join(__dirname, '..');
+require('module-alias').addAliases({
+    '@client': path.join(coreRoot, 'client'),
+    '@common': path.join(coreRoot, 'common'),
+    '@server': path.join(coreRoot, 'server'),
+});
+process.env.TS_NODE_PROJECT = path.join(coreRoot, 'cli', 'tsconfig.json');
+process.env.TS_NODE_TRANSPILE_ONLY = '1';
+require('ts-node/register/transpile-only');
+
+const appContainerStub = {
+    Environment: {
+        profile: 'test',
+        connectedProjects: [],
+    },
+    Identity: {},
+    Setup: {},
+    Console: {
+        createBugReport: () => {},
+    },
+    Trace: {
+        finishRequest: () => {},
+        record: () => {},
+        releaseRequest: () => {},
+    },
+    handleBug: () => {},
+};
+
+const applicationModulePath = path.join(coreRoot, 'server/app/index.ts');
+const originalLoad = Module._load;
+Module._load = function patchedLoad(request, parent, isMain) {
+    if (parent?.filename === applicationModulePath && request === './container') {
+        return { __esModule: true, default: appContainerStub };
+    }
+
+    return originalLoad.call(this, request, parent, isMain);
+};
+
+let Application;
+try {
+    Application = require('../server/app/index.ts').Application;
+} finally {
+    Module._load = originalLoad;
+}
+
+class TestApplication extends Application {}
+
+const createAppWithHooks = (hooks) => {
+    const app = new TestApplication();
+    app.hooks = hooks;
+
+    return app;
+};
+
+test('server application reports plain errors through the default error hook', async () => {
+    const events = [];
+    const request = { id: 'request-1' };
+    const app = createAppWithHooks({
+        error: [
+            async (error, hookRequest) => {
+                events.push({
+                    hook: 'error',
+                    message: error.message,
+                    requestId: hookRequest.id,
+                });
+            },
+        ],
+    });
+
+    await app.reportError(new Error('boom'), request);
+
+    assert.deepEqual(events, [{ hook: 'error', message: 'boom', requestId: 'request-1' }]);
+});
+
+test('server application reports HTTP errors through code-specific hooks', async () => {
+    const events = [];
+    const error = new Error('missing');
+    error.http = 404;
+    const request = { id: 'request-404' };
+    const app = createAppWithHooks({
+        'error.404': [
+            async (hookError, hookRequest) => {
+                events.push({
+                    hook: 'error.404',
+                    message: hookError.message,
+                    requestId: hookRequest.id,
+                });
+            },
+        ],
+    });
+
+    await app.reportError(error, request);
+
+    assert.deepEqual(events, [{ hook: 'error.404', message: 'missing', requestId: 'request-404' }]);
+});
+
+test('server application reports status errors through code-specific hooks', async () => {
+    const events = [];
+    const error = new Error('forbidden');
+    error.status = 403;
+    const app = createAppWithHooks({
+        'error.403': [
+            async (hookError) => {
+                events.push({
+                    hook: 'error.403',
+                    message: hookError.message,
+                });
+            },
+        ],
+    });
+
+    await app.reportError(error);
+
+    assert.deepEqual(events, [{ hook: 'error.403', message: 'forbidden' }]);
+});
+
+test('server application normalizes non-error rejections before reporting', async () => {
+    const messages = [];
+    const app = createAppWithHooks({
+        error: [
+            async (error) => {
+                messages.push(error.message);
+            },
+        ],
+    });
+
+    await app.reportError('string failure');
+    await app.reportError({ reason: 'unknown failure' });
+
+    assert.deepEqual(messages, ['string failure', 'Unknown application error']);
+});