proteum 2.5.0 → 2.5.2

package/eslint.js

@@ -16,23 +16,24 @@ const createZodTypeFactorySelector = (factoryName) =>
 
 const skippedTraversalKeys = new Set(['parent', 'loc', 'range', 'tokens', 'comments']);
 
-const traverseNode = (node, visit, parent = null, parentKey = null) => {
+const traverseNode = (node, visit, parent = null, parentKey = null, ancestors = []) => {
     if (!node || typeof node !== 'object') return;
 
-    visit(node, parent, parentKey);
+    visit(node, parent, parentKey, ancestors);
 
     for (const key of Object.keys(node)) {
         if (skippedTraversalKeys.has(key)) continue;
 
         const value = node[key];
+        const nextAncestors = [...ancestors, { node, childKey: key }];
         if (Array.isArray(value)) {
             value.forEach((child) => {
-                if (child && typeof child.type === 'string') traverseNode(child, visit, node, key);
+                if (child && typeof child.type === 'string') traverseNode(child, visit, node, key, nextAncestors);
             });
             continue;
         }
 
-        if (value && typeof value.type === 'string') traverseNode(value, visit, node, key);
+        if (value && typeof value.type === 'string') traverseNode(value, visit, node, key, nextAncestors);
     }
 };
 
@@ -121,77 +122,122 @@ const getCalleePropertyName = (callee) => {
     return null;
 };
 
-const preservingCallNames = new Set([
-    'captureError',
-    'captureException',
-    'consoleError',
-    'handleError',
-    'logError',
-    'onError',
-    'reject',
-    'reportError',
-    'setError',
-    'setErrorMessage',
-]);
-
-const preservingMemberNames = new Set(['captureException', 'error', 'handleError', 'reject', 'warn']);
-
-const isPreservingCall = (callExpression, names) => {
-    const propertyName = getCalleePropertyName(callExpression.callee);
-    if (!propertyName) return false;
-    if (callExpression.callee.type === 'MemberExpression' && callExpression.callee.object?.name === 'console')
-        return false;
-
-    const isKnownPreserver =
-        preservingCallNames.has(propertyName) ||
-        (callExpression.callee.type === 'MemberExpression' && preservingMemberNames.has(propertyName));
-
-    return isKnownPreserver && nodeReferencesName(callExpression, names);
+const getErrorHandlingSide = (filename) => {
+    const normalized = filename.replace(/\\/g, '/');
+    if (/(^|\/)client\//.test(normalized)) return 'client';
+    if (/(^|\/)(server|commands)\//.test(normalized)) return 'server';
+
+    return 'shared';
+};
+
+const getMemberPropertyName = (node) => {
+    if (node?.type !== 'MemberExpression') return null;
+    if (node.property.type === 'Identifier') return node.property.name;
+    if (node.property.type === 'Literal') return String(node.property.value);
+
+    return null;
+};
+
+const isConsoleMember = (node) =>
+    node?.type === 'MemberExpression' && node.object?.type === 'Identifier' && node.object.name === 'console';
+
+const isAppReceiver = (node) => {
+    if (!node) return false;
+    if (node.type === 'Identifier' && node.name === 'app') return true;
+    if (node.type === 'MemberExpression' && getMemberPropertyName(node) === 'app') return true;
+
+    return false;
+};
+
+const isClientErrorHandlerCall = (callExpression) =>
+    callExpression.callee.type === 'MemberExpression' &&
+    getMemberPropertyName(callExpression.callee) === 'handleError' &&
+    isAppReceiver(callExpression.callee.object);
+
+const isServerErrorReporterCall = (callExpression) =>
+    callExpression.callee.type === 'MemberExpression' &&
+    getMemberPropertyName(callExpression.callee) === 'reportError' &&
+    isAppReceiver(callExpression.callee.object);
+
+const isPromiseRejectCall = (callExpression) => getCalleePropertyName(callExpression.callee) === 'reject';
+
+const hasOptionalCallBoundary = (callExpression, ancestors = []) => {
+    if (callExpression.optional === true) return true;
+
+    let hasOptional = false;
+    traverseNode(callExpression.callee, (child) => {
+        if (child.type === 'ChainExpression' || child.optional === true) hasOptional = true;
+    });
+
+    return hasOptional || ancestors.some(({ node }) => node.type === 'ChainExpression');
 };
 
-const handlerPreservesCaughtError = (node, names) => {
+const isUnderConditionalControlFlow = (ancestors = []) =>
+    ancestors.some(({ node, childKey }) => {
+        if (node.type === 'IfStatement') return childKey === 'consequent' || childKey === 'alternate';
+        if (node.type === 'ConditionalExpression') return childKey === 'consequent' || childKey === 'alternate';
+        if (node.type === 'LogicalExpression') return childKey === 'right';
+        if (node.type === 'SwitchCase') return childKey === 'consequent';
+
+        return (
+            ['ForInStatement', 'ForOfStatement', 'ForStatement', 'WhileStatement', 'DoWhileStatement'].includes(
+                node.type,
+            ) && childKey === 'body'
+        );
+    });
+
+const isPreservingCall = (callExpression, names, side, ancestors = []) => {
+    if (!nodeReferencesName(callExpression, names)) return false;
+    if (hasOptionalCallBoundary(callExpression, ancestors)) return false;
+    if (isUnderConditionalControlFlow(ancestors)) return false;
+    if (isConsoleMember(callExpression.callee)) return false;
+    if (isPromiseRejectCall(callExpression)) return true;
+    if (side === 'client') return isClientErrorHandlerCall(callExpression);
+    if (side === 'server') return isServerErrorReporterCall(callExpression);
+
+    return isClientErrorHandlerCall(callExpression) || isServerErrorReporterCall(callExpression);
+};
+
+const handlerPreservesCaughtError = (node, names, side) => {
     let preserves = false;
 
-    traverseNode(node, (child) => {
-        if (child.type === 'ThrowStatement' && nodeReferencesName(child.argument, names)) preserves = true;
-        if (child.type === 'CallExpression' && isPreservingCall(child, names)) preserves = true;
+    traverseNode(node, (child, _parent, _parentKey, ancestors) => {
+        if (
+            child.type === 'ThrowStatement' &&
+            nodeReferencesName(child.argument, names) &&
+            !isUnderConditionalControlFlow(ancestors)
+        ) {
+            preserves = true;
+        }
+        if (child.type === 'CallExpression' && isPreservingCall(child, names, side, ancestors)) preserves = true;
     });
 
     return preserves;
 };
 
-const directPromiseCatchHandlers = new Set([
-    'captureError',
-    'captureException',
-    'consoleError',
-    'handleError',
-    'logError',
-    'reportError',
-]);
-
 const isDirectPromiseCatchHandler = (node) => {
     const name = getCalleePropertyName(node);
-    if (name && directPromiseCatchHandlers.has(name)) return true;
-    return false;
+    return name === 'reject';
 };
 
 const createSwallowedErrorRule = () => ({
     meta: {
         type: 'problem',
         docs: {
-            description: 'Require caught errors to be preserved, reported, rethrown, or surfaced with original detail.',
+            description: 'Require caught errors to reach the standard app error path or be rethrown.',
         },
         messages: {
             missingParam:
-                'Caught errors must be bound and preserved. Use `catch (error)` and rethrow, report, route, or surface original details.',
+                'Caught errors must be bound and routed through the standard error path. Use `catch (error)` and rethrow, call app.reportError on the server, or call app.handleError on the client.',
             unusedParam:
-                'Caught error `{{name}}` is discarded. Rethrow it, report it, route it to app error handling, or surface its original details.',
+                'Caught error `{{name}}` is discarded. Rethrow it, call app.reportError on the server, or call app.handleError on the client.',
             unpreserved:
-                'Caught error `{{name}}` is used but not preserved. Rethrow it, report it, route it, or surface original error details.',
+                'Caught error `{{name}}` is used but not routed through the standard error path. Rethrow it, call app.reportError on the server, or call app.handleError on the client.',
         },
         schema: [],
     },
     create(context) {
+        const side = getErrorHandlingSide(context.filename || context.getFilename?.() || '');
         const reportHandler = (node, params, body) => {
             const names = params.flatMap((param) => collectPatternNames(param));
             if (names.length === 0) {
@@ -205,7 +251,7 @@ const createSwallowedErrorRule = () => ({
                 return;
             }
 
-            if (!handlerPreservesCaughtError(body, collectDerivedErrorNames(body, names))) {
+            if (!handlerPreservesCaughtError(body, collectDerivedErrorNames(body, names), side)) {
                 context.report({ node, messageId: 'unpreserved', data: { name: referencedName } });
             }
         };

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "proteum",
 	"description": "LLM-first Opinionated Typescript Framework for web applications.",
-	"version": "2.5.0",
+	"version": "2.5.2",
 	"author": "Gaetan Le Gac (https://github.com/gaetanlegac)",
 	"repository": "git://github.com/gaetanlegac/proteum.git",
 	"license": "MIT",

package/server/app/index.ts

@@ -92,6 +92,24 @@ const createCommandsManager = (app: Application) => new CommandsManager(app, { d
 const createDevCommandsRegistry = (app: Application) => new DevCommandsRegistry(app);
 const createDevDiagnosticsRegistry = (app: Application) => new DevDiagnosticsRegistry(app);
 
+const normalizeReportedError = (rejection: unknown, fallbackMessage: string): Error => {
+    if (rejection instanceof Error) return rejection;
+    if (typeof rejection === 'string') return new Error(rejection);
+
+    return new Error(fallbackMessage);
+};
+
+const getNumericErrorProperty = (error: Error, property: 'http' | 'status' | 'statusCode') => {
+    const value = (error as Error & Partial<Record<typeof property, unknown>>)[property];
+    return typeof value === 'number' ? value : undefined;
+};
+
+const getErrorHttpCode = (error: Error) =>
+    getNumericErrorProperty(error, 'http') ??
+    getNumericErrorProperty(error, 'status') ??
+    getNumericErrorProperty(error, 'statusCode') ??
+    500;
+
 /*----------------------------------
 - FUNCTIONS
 ----------------------------------*/
@@ -138,12 +156,12 @@ export abstract class Application<
         // Handle unhandled crash
         this.on('error', (e, request) => this.container.handleBug(e, 'An error occured in the application', request));
 
-        process.on('unhandledRejection', (error: any, _promise: any) => {
+        process.on('unhandledRejection', (error: unknown) => {
             // Log so we know it's coming from unhandledRejection
             console.error('unhandledRejection', error);
 
             // We don't log the error here because it's the role of the app to decidehiw to log errors
-            this.runHook('error', error);
+            void this.reportError(error);
         });
 
         // We can't pass this in super so we assign here
@@ -155,6 +173,14 @@ export abstract class Application<
         return this.container.Console.createBugReport(new Anomaly(...anomalyArgs));
     }
 
+    public async reportError(rejection: unknown, request?: ServerRequest<TServerRouter>) {
+        const error = normalizeReportedError(rejection, 'Unknown application error');
+        const code = getErrorHttpCode(error);
+
+        if (code === 500) await this.runHook('error', error, request);
+        else await this.runHook('error.' + code, error, request);
+    }
+
     /*----------------------------------
     - COMMANDS
     ----------------------------------*/

package/server/services/router/index.ts

@@ -637,7 +637,7 @@ export default class ServerRouter<
                 error instanceof Error ? error : new Error(typeof error === 'string' ? error : 'Unknown request.finished hook error');
 
             try {
-                await this.app.runHook('error', typedError, request);
+                await this.app.reportError(typedError, request);
             } catch (hookError) {
                 console.error('request.finished hook error', typedError, 'Error hook failure', hookError);
             }
@@ -1111,7 +1111,7 @@ export default class ServerRouter<
             console.log(LogPrefix, 'Error catched from the router:', error);
 
             // Report error
-            await this.app.runHook('error', error, request);
+            await this.app.reportError(error, request);
 
             // Don't exose technical errors to users
             if (this.app.env.profile === 'prod')
@@ -1123,7 +1123,7 @@ export default class ServerRouter<
             /*if (this.app.env.profile === "dev")
                 console.warn(e);*/
 
-            await this.app.runHook('error.' + code, error, request);
+            await this.app.reportError(error, request);
         }
 
         // Return error based on the request format

package/tests/cli-mcp-command.test.cjs

@@ -205,6 +205,20 @@ test('mcp help describes projectId routing', () => {
     assert.match(output, /--stdio/);
 });
 
+test('verify help documents changed-file verification flags', () => {
+    const result = spawnSync(process.execPath, [cliBin, 'verify', '--help'], {
+        cwd: coreRoot,
+        encoding: 'utf8',
+    });
+    const output = `${result.stdout}\n${result.stderr}`;
+
+    assert.equal(result.status, 0);
+    assert.match(output, /changed/);
+    assert.match(output, /--staged/);
+    assert.match(output, /--base/);
+    assert.match(output, /--dry-run/);
+});
+
 test('mcp daemon launch prints a central MCP connection banner', async () => {
     const registryDir = fs.mkdtempSync(path.join(os.tmpdir(), 'proteum-mcp-daemon-launch-'));
     const reserveServer = http.createServer((req, res) => res.end('reserved'));

package/tests/client-app-error-handling.test.cjs

@@ -0,0 +1,100 @@
+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 previousLessExtension = require.extensions['.less'];
+require.extensions['.less'] = () => {};
+
+const clientContextStub = () => ({ side: 'client' });
+clientContextStub.default = clientContextStub;
+const originalLoad = Module._load;
+Module._load = function load(request, parent, isMain) {
+    if (request === '@/client/context') return clientContextStub;
+
+    return originalLoad.call(this, request, parent, isMain);
+};
+
+const previousWindow = global.window;
+const previousDocument = global.document;
+global.window = {
+    dev: false,
+    addEventListener: () => {},
+    removeEventListener: () => {},
+    history: {
+        state: {},
+        pushState: () => {},
+        replaceState: () => {},
+    },
+    location: {
+        hash: '',
+        pathname: '/',
+        search: '',
+        assign: () => {},
+    },
+};
+global.document = { defaultView: global.window };
+
+const {
+    default: Application,
+    getClientErrorMessage,
+    normalizeClientError,
+} = require('../client/app/index.ts');
+
+class TestApplication extends Application {
+    boot() {}
+    handleUpdate() {}
+}
+
+test('client error message normalization accepts unknown caught values', () => {
+    assert.equal(getClientErrorMessage(new Error('boom'), 'fallback'), 'boom');
+    assert.equal(getClientErrorMessage('string failure', 'fallback'), 'string failure');
+    assert.equal(getClientErrorMessage({ message: 'object failure' }, 'fallback'), 'object failure');
+    assert.equal(getClientErrorMessage({ code: 'UNKNOWN' }, 'fallback'), 'fallback');
+});
+
+test('client error normalization returns an Error instance', () => {
+    const existing = new Error('existing');
+
+    assert.equal(normalizeClientError(existing), existing);
+    assert.equal(normalizeClientError('string failure').message, 'string failure');
+    assert.equal(normalizeClientError({ code: 'UNKNOWN' }, 'fallback').message, 'fallback');
+});
+
+test('client app handleError logs and returns displayable message', () => {
+    const app = new TestApplication();
+    const logged = [];
+    const originalConsoleError = console.error;
+    console.error = (error) => {
+        logged.push(error);
+    };
+
+    try {
+        const message = app.handleError({ code: 'UNKNOWN' }, 'Unable to finish action.');
+
+        assert.equal(message, 'Unable to finish action.');
+        assert.equal(logged.length, 1);
+        assert.equal(logged[0] instanceof Error, true);
+        assert.equal(logged[0].message, 'Unable to finish action.');
+    } finally {
+        console.error = originalConsoleError;
+    }
+});
+
+afterAll(() => {
+    Module._load = originalLoad;
+    if (previousLessExtension === undefined) delete require.extensions['.less'];
+    else require.extensions['.less'] = previousLessExtension;
+    if (previousWindow === undefined) delete global.window;
+    else global.window = previousWindow;
+    if (previousDocument === undefined) delete global.document;
+    else global.document = previousDocument;
+});

package/tests/contracts-doctor.test.cjs

@@ -0,0 +1,98 @@
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const coreRoot = path.resolve(__dirname, '..');
+process.env.TS_NODE_PROJECT = path.join(coreRoot, 'tsconfig.json');
+process.env.TS_NODE_TRANSPILE_ONLY = '1';
+require('ts-node/register/transpile-only');
+
+const { buildContractsDoctorResponse } = require('../common/dev/contractsDoctor.ts');
+
+const touch = (filepath, content = '') => {
+    fs.mkdirSync(path.dirname(filepath), { recursive: true });
+    fs.writeFileSync(filepath, content);
+};
+
+const createManifest = (appRoot, pageFilepath) => ({
+    app: {
+        identityFilepath: path.join(appRoot, 'identity.config.ts'),
+        root: appRoot,
+        setupFilepath: path.join(appRoot, 'proteum.config.ts'),
+    },
+    connectedProjects: [],
+    commands: [],
+    controllers: [],
+    layouts: [],
+    routes: {
+        client: [
+            {
+                chunkFilepath: 'landing/index',
+                filepath: pageFilepath,
+            },
+        ],
+        server: [],
+    },
+    services: {
+        app: [],
+        routerPlugins: [],
+    },
+});
+
+test('contracts doctor allows hooks inside definePageRoute render callbacks', () => {
+    const appRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'proteum-contracts-doctor-'));
+    const pageFilepath = path.join(appRoot, 'client/pages/landing/index.tsx');
+
+    touch(path.join(appRoot, 'proteum.config.ts'), 'export default {};');
+    touch(path.join(appRoot, 'identity.config.ts'), 'export default {};');
+    touch(path.join(appRoot, 'client/hooks/useToast.ts'), 'export default function useToast() { return () => undefined; }');
+    touch(
+        pageFilepath,
+        `import { definePageRoute } from '@common/router/definitions';
+import useToast from '@/client/hooks/useToast';
+
+export default definePageRoute({
+    path: '/',
+    options: {},
+    data: null,
+    render: () => {
+        const toast = useToast();
+        return toast ? null : null;
+    },
+});
+`,
+    );
+
+    for (const filepath of [
+        'proteum.connected.json',
+        '.proteum/manifest.json',
+        '.proteum/proteum.connected.d.ts',
+        '.proteum/client/context.ts',
+        '.proteum/client/controllers.ts',
+        '.proteum/client/layouts.ts',
+        '.proteum/client/models.ts',
+        '.proteum/client/routes.ts',
+        '.proteum/client/services.d.ts',
+        '.proteum/common/controllers.ts',
+        '.proteum/common/models.ts',
+        '.proteum/common/services.d.ts',
+        '.proteum/server/commands.app.d.ts',
+        '.proteum/server/commands.d.ts',
+        '.proteum/server/commands.ts',
+        '.proteum/server/controllers.ts',
+        '.proteum/server/models.ts',
+        '.proteum/server/routes.ts',
+        '.proteum/server/services.d.ts',
+        '.proteum/client/route-modules/landing/index.tsx',
+        '.proteum/server/route-modules/client/pages/landing/index.tsx',
+    ]) {
+        touch(path.join(appRoot, filepath));
+    }
+
+    const response = buildContractsDoctorResponse(createManifest(appRoot, pageFilepath));
+    assert.equal(
+        response.diagnostics.some((diagnostic) => diagnostic.code === 'runtime/provider-hook-outside-provider'),
+        false,
+    );
+});