proteum 2.5.15 → 2.5.17

package/agents/project/CODING_STYLE.md

@@ -107,6 +107,8 @@ Two rules police the edges of the type system and the error path. Both allow the
 - 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

package/eslint.js

@@ -183,6 +183,8 @@ const hasOptionalCallBoundary = (callExpression, ancestors = []) => {
     return hasOptional || ancestors.some(({ node }) => node.type === 'ChainExpression');
 };
 
+// A loop body is iteration, not a condition. `for (const item of batch) item.reject(error)`
+// preserves the error for every item there is, so it is not a swallow.
 const isUnderConditionalControlFlow = (ancestors = []) =>
     ancestors.some(({ node, childKey }) => {
         if (node.type === 'IfStatement') return childKey === 'consequent' || childKey === 'alternate';
@@ -190,13 +192,33 @@ const isUnderConditionalControlFlow = (ancestors = []) =>
         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'
-        );
+        return false;
+    });
+
+/**
+ * Does the handler throw, whatever it throws?
+ *
+ * `catch { throw new Error('must be an absolute URL') }` translates a failure
+ * into the domain's own vocabulary. The original object is dropped, but the
+ * failure still propagates and nothing continues silently, which is what this
+ * rule exists to prevent. Attaching the original as `cause` is better practice,
+ * not a separate correctness question for this rule.
+ */
+const handlerThrows = (node) => {
+    let throws = false;
+
+    traverseNode(node, (child, _parent, _parentKey, ancestors) => {
+        if (child.type === 'ThrowStatement' && !isUnderConditionalControlFlow(ancestors)) throws = true;
     });
 
+    return throws;
+};
+
+// A returned fallback is deliberately NOT accepted. `catch { return null }` is
+// the textbook swallow, and no structural signal separates it from
+// `.catch(() => [])`. Where a fallback really is correct, the call site says so
+// with a disable comment and a reason, which stays greppable.
+
 const defaultErrorReporters = ['app.reportError', 'app.handleError'];
 
 /**
@@ -363,6 +385,11 @@ const createSwallowedErrorRule = () => ({
         const reportHandler = (node, params, body) => {
             const names = params.flatMap((param) => collectPatternNames(param));
             if (names.length === 0) {
+                // Nothing was bound, so nothing can be routed. Still accepted when
+                // the handler translates the failure into a throw, because the
+                // failure keeps propagating rather than being continued past.
+                if (handlerThrows(body)) return;
+
                 context.report({ node, messageId: 'missingParam' });
                 return;
             }
@@ -373,6 +400,8 @@ const createSwallowedErrorRule = () => ({
                 return;
             }
 
+            if (handlerThrows(body)) return;
+
             if (!handlerPreservesCaughtError(body, collectDerivedErrorNames(body, names), side, reporters)) {
                 context.report({ node, messageId: 'unpreserved', data: { name: referencedName } });
             }
@@ -407,14 +436,39 @@ const boundaryTagPattern = /(^|\s)@boundary(\s|$)/;
  * value is DomainField` is the correct signature. Any narrower input type would
  * defeat the guard it belongs to.
  */
-const isWithinTypeGuardSignature = (ancestors) =>
-    ancestors.some(({ node }) => {
-        const returnType = node?.returnType?.typeAnnotation;
-        return returnType?.type === 'TSTypePredicate';
-    });
+const isWithinTypeGuardSignature = (node) => {
+    let current = node.parent;
+    while (current) {
+        if (current.returnType?.typeAnnotation?.type === 'TSTypePredicate') return true;
+        current = current.parent;
+    }
 
-const isWithinCatchParameter = (ancestors) =>
-    ancestors.some(({ node, childKey }) => node?.type === 'CatchClause' && childKey === 'param');
+    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: {
@@ -440,13 +494,14 @@ const createNoLooseUnknownRule = () => ({
             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;
-            let depth = 0;
-            while (current && depth < 6) {
+            while (current && current.type !== 'Program') {
                 const ancestorComments = sourceCode.getCommentsBefore?.(current) || [];
                 if (ancestorComments.some((comment) => boundaryTagPattern.test(comment.value))) return true;
                 current = current.parent;
-                depth += 1;
             }
 
             return false;
@@ -454,21 +509,10 @@ const createNoLooseUnknownRule = () => ({
 
         return {
             TSUnknownKeyword(node) {
-                const ancestors = [];
-                let current = node.parent;
-                while (current) {
-                    ancestors.push({ childKey: null, node: current });
-                    current = current.parent;
-                }
-
                 // TypeScript itself types a catch binding as `unknown`, so banning
                 // it there bans the language's own contract.
-                if (node.parent?.type === 'TSTypeAnnotation' && node.parent.parent?.type === 'Identifier') {
-                    const owner = node.parent.parent.parent;
-                    if (owner?.type === 'CatchClause') return;
-                }
-                if (isWithinCatchParameter(ancestors)) return;
-                if (isWithinTypeGuardSignature(ancestors)) return;
+                if (isWithinCatchParameter(node)) return;
+                if (isWithinTypeGuardSignature(node)) return;
                 if (hasBoundaryTag(node)) return;
 
                 context.report({ node, messageId: 'looseUnknown' });
@@ -859,12 +903,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],
@@ -936,8 +988,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.15",
+	"version": "2.5.17",
 	"author": "Gaetan Le Gac (https://github.com/gaetanlegac)",
 	"repository": "git://github.com/gaetanlegac/proteum.git",
 	"license": "MIT",

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

@@ -36,6 +36,21 @@ test('unknown is allowed on a catch binding, which is how TypeScript types it',
     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';
@@ -59,6 +74,32 @@ test('an undocumented parse boundary is still reported', () => {
     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
 ----------------------------------*/
@@ -199,6 +240,46 @@ test('an error pushed into a result collection counts as preservation', () => {
     assert.equal(count(messages, swallowedRuleId), 0);
 });
 
+test('translating a failure into a new throw counts, even without the original', () => {
+    const messages = lint(`
+        export const assertUrl = (raw) => {
+            try {
+                return new URL(raw);
+            } catch {
+                throw new Error('must be an absolute URL');
+            }
+        };
+    `);
+
+    assert.equal(count(messages, swallowedRuleId), 0);
+});
+
+test('preservation inside a loop body counts, because iteration is not a condition', () => {
+    const messages = lint(`
+        export const run = (batch) => {
+            load().catch((error) => {
+                for (const item of batch) {
+                    item.reject(error);
+                }
+            });
+        };
+    `);
+
+    assert.equal(count(messages, swallowedRuleId), 0);
+});
+
+test('a returned fallback is still a swallow, however it is spelled', () => {
+    const nullFallback = lint(`
+        export const run = () => {
+            try { risky(); } catch { return null; }
+        };
+    `);
+    assert.equal(count(nullFallback, swallowedRuleId), 1);
+
+    const emptyList = lint(`export const run = (d) => dns.resolveMx(d).catch(() => []);`);
+    assert.equal(count(emptyList, swallowedRuleId), 1);
+});
+
 test('a console-only catch is still reported', () => {
     const messages = lint(`
         export const run = async () => {