proteum 2.5.15 → 2.5.16

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

@@ -407,14 +407,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;
+    }
+
+    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;
+    }
 
-const isWithinCatchParameter = (ancestors) =>
-    ancestors.some(({ node, childKey }) => node?.type === 'CatchClause' && childKey === 'param');
+    return false;
+};
 
 const createNoLooseUnknownRule = () => ({
     meta: {
@@ -440,13 +465,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 +480,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 +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],
@@ -936,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.15",
+	"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

@@ -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
 ----------------------------------*/