proteum 2.5.14 → 2.5.16

package/agents/project/CODING_STYLE.md

@@ -97,6 +97,29 @@ The read-only MCP owner payloads return these anchors alongside `explain_summary
 
 `proteum docs check` verifies the whole corpus in both directions: it fails on an anchor that no longer resolves, and reports as a backlog every fix note carrying an `Agent warning` that no code anchors, plus every feature pack nothing points at. `proteum verify changed` selects it automatically whenever `docs/**` or a source file changes, so a renamed document cannot silently orphan an anchor.
 
+## Trust boundaries and caught errors
+
+Two rules police the edges of the type system and the error path. Both allow the correct idiom and report the lazy one, so read the message before reaching for a disable comment.
+
+`proteum/no-loose-unknown` reports `unknown` because it usually hides a contract that should be written down. It allows `unknown` in three places, because there it is the correct and safe answer:
+
+- a catch binding, which is how TypeScript types it;
+- the input of a type guard, since narrowing an untrusted value is the guard's whole job;
+- anything carrying a `@boundary` tag in its doc comment.
+
+Test files are exempt from this rule entirely: a fixture built with `as unknown as X` is a test technique, not a trust boundary. The other rules still apply in tests.
+
+Use `@boundary` when the value genuinely arrives from outside: a parsed response, a provider payload, a third-party shim. State where it comes from, so the codebase's trust boundaries stay greppable:
+
+```typescript
+/** @boundary HumbleWorth prediction output, shape owned by the provider. */
+export const parseOutput = (output: unknown) => ...
+```
+
+`proteum/no-swallowed-caught-error` requires a caught error to reach somewhere. It accepts a rethrow, `Promise.reject`, `next(error)` for Express propagation, an error surfaced to the caller as a returned or pushed result, and the reporters configured through `errorReporters`. It also accepts preservation guarded by a condition **about the error**, because choosing which failures to report is a decision. It still reports a guard on whether the reporter exists, such as `if (app) app.reportError(error)`, because the error is lost whenever it does not.
+
+`console.error(error)` is not error handling and never satisfies either rule.
+
 ## Self-check before finishing
 
 Re-scan every touched file against this list before declaring the work done:

package/eslint.js

@@ -197,32 +197,131 @@ const isUnderConditionalControlFlow = (ancestors = []) =>
         );
     });
 
-const isPreservingCall = (callExpression, names, side, ancestors = []) => {
+const defaultErrorReporters = ['app.reportError', 'app.handleError'];
+
+/**
+ * Does this call match one of the configured `receiver.method` reporters?
+ *
+ * The receiver may be a bare identifier or the property of a longer chain, so
+ * `app.reportError(...)`, `this.app.reportError(...)` and `ctx.app.report(...)`
+ * all match a `app.reportError` entry.
+ */
+const matchesConfiguredReporter = (callExpression, reporters) => {
+    const method = getMemberPropertyName(callExpression.callee);
+    if (!method) return false;
+
+    // Only project-added reporters are matched here. The built-in two stay with
+    // the side logic below, so a server file calling the client's `handleError`
+    // is still reported rather than quietly accepted.
+    const extraReporters = reporters.filter((reporter) => !defaultErrorReporters.includes(reporter));
+
+    return extraReporters.some((reporter) => {
+        const [receiverName, methodName] = reporter.includes('.') ? reporter.split('.') : [null, reporter];
+        if (method !== methodName) return false;
+        if (receiverName === null) return true;
+
+        const receiver = callExpression.callee.object;
+        if (receiver?.type === 'Identifier') return receiver.name === receiverName;
+
+        return getMemberPropertyName(receiver) === receiverName;
+    });
+};
+
+/**
+ * Express hands a caught error to its error middleware with `next(error)`. That
+ * is the framework's own propagation path, so treating it as a swallow would
+ * report the correct implementation of every route handler.
+ */
+const isFrameworkPropagationCall = (callExpression, names) =>
+    callExpression.callee?.type === 'Identifier' &&
+    callExpression.callee.name === 'next' &&
+    (callExpression.arguments || []).some((argument) => nodeReferencesName(argument, names));
+
+const isPreservingCall = (callExpression, names, side, ancestors = [], reporters = defaultErrorReporters) => {
     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 (isFrameworkPropagationCall(callExpression, names)) return true;
+    if (matchesConfiguredReporter(callExpression, reporters)) return true;
     if (side === 'client') return isClientErrorHandlerCall(callExpression);
     if (side === 'server') return isServerErrorReporterCall(callExpression);
 
     return isClientErrorHandlerCall(callExpression) || isServerErrorReporterCall(callExpression);
 };
 
-const handlerPreservesCaughtError = (node, names, side) => {
+/**
+ * Is the caught error handed back to the caller as a value?
+ *
+ * `return { ok: false, message: error.message }` and
+ * `results.push({ state: 'unavailable', message: describeError(error) })` both
+ * surface the failure in the API's own vocabulary. That is a designed
+ * degradation path, not a loss, so it counts as preservation.
+ */
+const handlerSurfacesCaughtError = (node, names) => {
+    let surfaces = false;
+
+    traverseNode(node, (child) => {
+        if (child.type === 'ReturnStatement' && nodeReferencesName(child.argument, names)) surfaces = true;
+
+        if (
+            child.type === 'CallExpression' &&
+            ['push', 'unshift', 'add', 'set'].includes(getCalleePropertyName(child.callee) || '') &&
+            (child.arguments || []).some((argument) => nodeReferencesName(argument, names))
+        ) {
+            surfaces = true;
+        }
+    });
+
+    return surfaces;
+};
+
+/**
+ * Is preservation guarded by a condition that tests the caught error itself?
+ *
+ * `if (!(error instanceof ExpectedPause)) report(error)` is deliberate
+ * filtering: the author chose which failures are worth reporting, which is a
+ * decision rather than a swallow. `if (app) app.reportError(error)` is not: it
+ * gates on whether the reporter exists, so the error is lost whenever it does
+ * not. Only the first is accepted.
+ */
+const isGuardedByErrorPredicate = (ancestors, names) =>
+    ancestors.some(({ node, childKey }) => {
+        if (node.type === 'IfStatement' && (childKey === 'consequent' || childKey === 'alternate'))
+            return nodeReferencesName(node.test, names);
+        if (node.type === 'ConditionalExpression' && (childKey === 'consequent' || childKey === 'alternate'))
+            return nodeReferencesName(node.test, names);
+        if (node.type === 'LogicalExpression' && childKey === 'right') return nodeReferencesName(node.left, names);
+        if (node.type === 'SwitchCase' && childKey === 'consequent') return true;
+
+        return false;
+    });
+
+const preservationSurvivesControlFlow = (ancestors, names) =>
+    !isUnderConditionalControlFlow(ancestors) || isGuardedByErrorPredicate(ancestors, names);
+
+const handlerPreservesCaughtError = (node, names, side, reporters = defaultErrorReporters) => {
     let preserves = false;
 
     traverseNode(node, (child, _parent, _parentKey, ancestors) => {
         if (
             child.type === 'ThrowStatement' &&
             nodeReferencesName(child.argument, names) &&
-            !isUnderConditionalControlFlow(ancestors)
+            preservationSurvivesControlFlow(ancestors, names)
+        ) {
+            preserves = true;
+        }
+        if (
+            child.type === 'CallExpression' &&
+            isPreservingCall(child, names, side, ancestors, reporters) &&
+            preservationSurvivesControlFlow(ancestors, names)
         ) {
             preserves = true;
         }
-        if (child.type === 'CallExpression' && isPreservingCall(child, names, side, ancestors)) preserves = true;
     });
 
+    if (!preserves && handlerSurfacesCaughtError(node, names)) preserves = true;
+
     return preserves;
 };
 
@@ -245,10 +344,22 @@ const createSwallowedErrorRule = () => ({
             unpreserved:
                 '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: [],
+        schema: [
+            {
+                type: 'object',
+                properties: {
+                    // `receiver.method` or a bare `method`. A project whose error
+                    // path is not `app.reportError` names it here rather than
+                    // being told its own convention is a swallow.
+                    reporters: { type: 'array', items: { type: 'string' } },
+                },
+                additionalProperties: false,
+            },
+        ],
     },
     create(context) {
         const side = getErrorHandlingSide(context.filename || context.getFilename?.() || '');
+        const reporters = context.options?.[0]?.reporters || defaultErrorReporters;
         const reportHandler = (node, params, body) => {
             const names = params.flatMap((param) => collectPatternNames(param));
             if (names.length === 0) {
@@ -262,7 +373,7 @@ const createSwallowedErrorRule = () => ({
                 return;
             }
 
-            if (!handlerPreservesCaughtError(body, collectDerivedErrorNames(body, names), side)) {
+            if (!handlerPreservesCaughtError(body, collectDerivedErrorNames(body, names), side, reporters)) {
                 context.report({ node, messageId: 'unpreserved', data: { name: referencedName } });
             }
         };
@@ -287,6 +398,100 @@ const createSwallowedErrorRule = () => ({
     },
 });
 
+const boundaryTagPattern = /(^|\s)@boundary(\s|$)/;
+
+/**
+ * Is this `unknown` inside a function whose return type is a type predicate?
+ *
+ * Narrowing an untrusted value is the entire job of a guard, so `(value: unknown):
+ * value is DomainField` is the correct signature. Any narrower input type would
+ * defeat the guard it belongs to.
+ */
+const isWithinTypeGuardSignature = (node) => {
+    let current = node.parent;
+    while (current) {
+        if (current.returnType?.typeAnnotation?.type === 'TSTypePredicate') return true;
+        current = current.parent;
+    }
+
+    return false;
+};
+
+/**
+ * Is this `unknown` inside the *parameter* of a catch clause?
+ *
+ * Range containment rather than a parent-chain shape check, so a destructured or
+ * annotated binding qualifies too. The containment test matters: the catch BODY
+ * also has the clause as an ancestor, and `unknown` there is not the language's
+ * doing and still needs a reason.
+ */
+const isWithinCatchParameter = (node) => {
+    let current = node.parent;
+    while (current) {
+        if (current.type === 'CatchClause') {
+            return (
+                current.param != null &&
+                node.range[0] >= current.param.range[0] &&
+                node.range[1] <= current.param.range[1]
+            );
+        }
+        current = current.parent;
+    }
+
+    return false;
+};
+
+const createNoLooseUnknownRule = () => ({
+    meta: {
+        type: 'problem',
+        docs: {
+            description: 'Disallow `unknown` except where a value genuinely crosses a trust boundary.',
+        },
+        messages: {
+            looseUnknown:
+                '`unknown` hides a contract that should be typed. Define the explicit type, or, when the value really does arrive from outside (a parsed response, a provider payload, a caught error), document it with a `@boundary` comment saying where it comes from.',
+        },
+        schema: [],
+    },
+    create(context) {
+        const sourceCode = getSourceCode(context);
+
+        // A `@boundary` tag anywhere above the declaration marks a deliberate
+        // trust boundary. Requiring the tag rather than allowing `unknown`
+        // silently keeps the boundaries greppable and forces a written reason.
+        const hasBoundaryTag = (node) => {
+            if (!sourceCode) return false;
+
+            const comments = sourceCode.getCommentsBefore?.(node) || [];
+            if (comments.some((comment) => boundaryTagPattern.test(comment.value))) return true;
+
+            // Walk to the enclosing declaration rather than a fixed few levels:
+            // a nested position such as `{ query(v?: readonly unknown[]): Promise<unknown> }`
+            // sits eight or more nodes below the parameter the tag documents.
+            let current = node.parent;
+            while (current && current.type !== 'Program') {
+                const ancestorComments = sourceCode.getCommentsBefore?.(current) || [];
+                if (ancestorComments.some((comment) => boundaryTagPattern.test(comment.value))) return true;
+                current = current.parent;
+            }
+
+            return false;
+        };
+
+        return {
+            TSUnknownKeyword(node) {
+                // TypeScript itself types a catch binding as `unknown`, so banning
+                // it there bans the language's own contract.
+                if (isWithinCatchParameter(node)) return;
+                if (isWithinTypeGuardSignature(node)) return;
+                if (hasBoundaryTag(node)) return;
+
+                context.report({ node, messageId: 'looseUnknown' });
+            },
+        };
+    },
+});
+
 const createNoAppImportRule = () => ({
     meta: {
         type: 'problem',
@@ -669,11 +874,20 @@ const createValidDocAnchorRule = () => ({
     },
 });
 
+const defaultTestFilePatterns = [
+    '**/*.test.{ts,tsx,mts,cts}',
+    '**/*.spec.{ts,tsx,mts,cts}',
+    '**/*.node-test.{ts,tsx,mts,cts}',
+    '**/tests/**/*.{ts,tsx,mts,cts}',
+];
+
 const createProteumEslintConfig = ({
     docAnchors = 'warn',
+    errorReporters = defaultErrorReporters,
     excludeDocAnchors = [],
     includeDocAnchors = [],
     ignores = [],
+    testFiles = defaultTestFilePatterns,
 } = {}) => [
     {
         ignores: [...defaultIgnores, ...ignores],
@@ -700,6 +914,7 @@ const createProteumEslintConfig = ({
             proteum: {
                 rules: {
                     'no-app-import': createNoAppImportRule(),
+                    'no-loose-unknown': createNoLooseUnknownRule(),
                     'no-swallowed-caught-error': createSwallowedErrorRule(),
                     'require-doc-anchor': createRequireDocAnchorRule(),
                     'valid-doc-anchor': createValidDocAnchorRule(),
@@ -712,7 +927,7 @@ const createProteumEslintConfig = ({
         rules: {
             '@typescript-eslint/no-explicit-any': 'error',
             'proteum/no-app-import': 'error',
-            'proteum/no-swallowed-caught-error': 'error',
+            'proteum/no-swallowed-caught-error': ['error', { reporters: errorReporters }],
             // Missing anchors warn by default so adopting apps see the backlog
             // without a failing build; pass `docAnchors: 'error'` once backfilled.
             // Routes, controllers and service classes are covered automatically.
@@ -727,12 +942,12 @@ const createProteumEslintConfig = ({
             // already opted in, and a pointer to a deleted document is worse
             // than no pointer at all.
             'proteum/valid-doc-anchor': docAnchors === 'off' ? 'off' : 'error',
+            // Replaces the old bare `TSUnknownKeyword` selector. A selector has no
+            // context, so it could not tell an internal contract that should be
+            // typed from a value that genuinely arrives from outside.
+            'proteum/no-loose-unknown': 'error',
             'no-restricted-syntax': [
                 'error',
-                {
-                    selector: 'TSUnknownKeyword',
-                    message: 'Do not use `unknown`; define an explicit type instead.',
-                },
                 {
                     selector: createZodTypeFactorySelector('any'),
                     message: 'Do not use Zod `any()` schemas; define an explicit schema instead.',
@@ -744,8 +959,19 @@ const createProteumEslintConfig = ({
             ],
         },
     },
+    {
+        // A test fixture deliberately builds a shape the production types forbid,
+        // usually through `as unknown as X` or a partial mock. That is a test
+        // technique, not a trust boundary, so demanding a `@boundary` reason for
+        // each one would add noise without documenting anything real.
+        files: testFiles,
+        rules: {
+            'proteum/no-loose-unknown': 'off',
+        },
+    },
 ];
 
 module.exports = {
     createProteumEslintConfig,
+    defaultTestFilePatterns,
 };

package/package.json

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

package/tests/error-boundary-rules.test.cjs

@@ -0,0 +1,269 @@
+const assert = require('node:assert/strict');
+const { Linter } = require('eslint');
+
+const { createProteumEslintConfig } = require('../eslint.js');
+
+const lint = (code, filename = 'server/example.ts', options) => {
+    const linter = new Linter({ configType: 'flat' });
+    return linter.verify(code, createProteumEslintConfig(options), { filename });
+};
+
+const looseUnknownRuleId = 'proteum/no-loose-unknown';
+const swallowedRuleId = 'proteum/no-swallowed-caught-error';
+const count = (messages, ruleId) => messages.filter((message) => message.ruleId === ruleId).length;
+
+/*----------------------------------
+- no-loose-unknown
+----------------------------------*/
+
+test('loose unknown is still reported on an ordinary contract', () => {
+    const messages = lint(`export type TRow = { value: unknown };`);
+
+    assert.equal(count(messages, looseUnknownRuleId), 1);
+});
+
+test('unknown is allowed on a catch binding, which is how TypeScript types it', () => {
+    const messages = lint(`
+        export const run = () => {
+            try {
+                risky();
+            } catch (error: unknown) {
+                throw error;
+            }
+        };
+    `);
+
+    assert.equal(count(messages, looseUnknownRuleId), 0);
+});
+
+test('unknown inside a catch BODY still needs a reason, only the binding is exempt', () => {
+    const messages = lint(`
+        export const run = () => {
+            try {
+                risky();
+            } catch (error: unknown) {
+                const detail: unknown = extract(error);
+                throw error;
+            }
+        };
+    `);
+
+    assert.equal(count(messages, looseUnknownRuleId), 1);
+});
+
+test('unknown is allowed as the input of a type guard', () => {
+    const messages = lint(`
+        export const isDomainField = (value: unknown): value is string => typeof value === 'string';
+    `);
+
+    assert.equal(count(messages, looseUnknownRuleId), 0);
+});
+
+test('unknown is allowed when the trust boundary is documented', () => {
+    const messages = lint(`
+        /** @boundary HumbleWorth prediction output, shape owned by the provider. */
+        export const parseOutput = (output: unknown) => output;
+    `);
+
+    assert.equal(count(messages, looseUnknownRuleId), 0);
+});
+
+test('an undocumented parse boundary is still reported', () => {
+    const messages = lint(`export const parseOutput = (output: unknown) => output;`);
+
+    assert.equal(count(messages, looseUnknownRuleId), 1);
+});
+
+test('test files may use unknown without a boundary reason', () => {
+    const fixture = `const STATUS_RULE = [{ filterId: 'status' }] as unknown as RadarRulesContract;`;
+
+    assert.equal(count(lint(fixture, 'server/example.ts'), looseUnknownRuleId), 1);
+    assert.equal(count(lint(fixture, 'server/example.test.ts'), looseUnknownRuleId), 0);
+    assert.equal(count(lint(fixture, 'src/Domains/PendingList.node-test.ts'), looseUnknownRuleId), 0);
+    assert.equal(count(lint(fixture, 'tests/unit/scope-builder.ts'), looseUnknownRuleId), 0);
+});
+
+test('the other rules still apply inside test files', () => {
+    const messages = lint(
+        `
+            export const run = async () => {
+                try {
+                    await load();
+                } catch (error) {
+                    console.error('load failed', error);
+                }
+            };
+        `,
+        'server/example.test.ts',
+    );
+
+    assert.equal(count(messages, swallowedRuleId), 1);
+});
+
+/*----------------------------------
+- no-swallowed-caught-error
+----------------------------------*/
+
+test('express next(error) counts as propagation', () => {
+    const messages = lint(`
+        export const handler = async (req, res, next) => {
+            try {
+                await load();
+            } catch (error) {
+                next(error);
+            }
+        };
+    `);
+
+    assert.equal(count(messages, swallowedRuleId), 0);
+});
+
+test('a configured reporter counts as preservation', () => {
+    const source = `
+        export class Scanner {
+            public async run() {
+                try {
+                    await this.scan();
+                } catch (error) {
+                    this.app.reportError(error, { source: 'scan', code: 'failed' });
+                }
+            }
+        }
+    `;
+
+    assert.equal(count(lint(source), swallowedRuleId), 0);
+
+    // A project whose error path has another name declares it rather than being
+    // told its own convention is a swallow.
+    const custom = `
+        export class Scanner {
+            public async run() {
+                try {
+                    await this.scan();
+                } catch (error) {
+                    this.app.report('scan failed', error);
+                }
+            }
+        }
+    `;
+
+    assert.equal(count(lint(custom), swallowedRuleId), 1);
+    assert.equal(
+        count(lint(custom, 'server/example.ts', { errorReporters: ['app.reportError', 'app.report'] }), swallowedRuleId),
+        0,
+    );
+});
+
+test('conditional preservation counts, because deliberate filtering is not a swallow', () => {
+    const messages = lint(`
+        export class Scanner {
+            public async run() {
+                try {
+                    await this.scan();
+                } catch (error) {
+                    if (!(error instanceof ExpectedPause)) {
+                        this.app.reportError(error, { source: 'scan', code: 'failed' });
+                    }
+                }
+            }
+        }
+    `);
+
+    assert.equal(count(messages, swallowedRuleId), 0);
+});
+
+test('a guard on the reporter existing is still a swallow, unlike a guard on the error', () => {
+    // Filtering by what the error is: a decision.
+    const filtered = lint(`
+        export const run = async () => {
+            try {
+                await load();
+            } catch (error) {
+                if (error.code !== 'EXPECTED') app.reportError(error);
+            }
+        };
+    `);
+    assert.equal(count(filtered, swallowedRuleId), 0);
+
+    // Gating on whether the reporter exists: the error vanishes when it does not.
+    const gated = lint(`
+        export const run = async (app) => {
+            try {
+                await load();
+            } catch (error) {
+                if (app) app.reportError(error);
+            }
+        };
+    `);
+    assert.equal(count(gated, swallowedRuleId), 1);
+});
+
+test('a guarded rethrow counts as preservation', () => {
+    const messages = lint(`
+        export const run = async () => {
+            try {
+                await load();
+            } catch (error) {
+                if (error.code !== 'ENOENT') throw error;
+            }
+        };
+    `);
+
+    assert.equal(count(messages, swallowedRuleId), 0);
+});
+
+test('an error surfaced as a returned result counts as preservation', () => {
+    const messages = lint(`
+        export const run = async () => {
+            try {
+                await load();
+            } catch (error) {
+                return { ok: false, message: error.message };
+            }
+        };
+    `);
+
+    assert.equal(count(messages, swallowedRuleId), 0);
+});
+
+test('an error pushed into a result collection counts as preservation', () => {
+    const messages = lint(`
+        export const run = async (results) => {
+            try {
+                await load();
+            } catch (error) {
+                results.push({ state: 'unavailable', message: describeError(error) });
+            }
+        };
+    `);
+
+    assert.equal(count(messages, swallowedRuleId), 0);
+});
+
+test('a console-only catch is still reported', () => {
+    const messages = lint(`
+        export const run = async () => {
+            try {
+                await load();
+            } catch (error) {
+                console.error('load failed', error);
+            }
+        };
+    `);
+
+    assert.equal(count(messages, swallowedRuleId), 1);
+});
+
+test('a discarded error is still reported', () => {
+    const messages = lint(`
+        export const run = async () => {
+            try {
+                await load();
+            } catch (error) {
+                return null;
+            }
+        };
+    `);
+
+    assert.equal(count(messages, swallowedRuleId), 1);
+});