@blumintinc/eslint-plugin-blumint 1.20.71 → 1.20.72

package/lib/index.js

@@ -223,7 +223,7 @@ function noFrontendImportsFromFunctionsPatterns(pattern) {
 module.exports = {
     meta: {
         name: '@blumintinc/eslint-plugin-blumint',
-        version: '1.20.71',
+        version: '1.20.72',
     },
     parseOptions: {
         ecmaVersion: 2020,

package/lib/rules/enforce-firestore-doc-ref-generic.js

@@ -277,23 +277,53 @@ exports.enforceFirestoreDocRefGeneric = (0, createRule_1.createRule)({
                         member.key.type === utils_1.AST_NODE_TYPES.Identifier &&
                         member.key.name === property.name);
                     if (getter) {
-                        // Check explicit return type
-                        if (getter.value.returnType) {
-                            return hasCollectionReferenceType(getter.value.returnType.typeAnnotation);
-                        }
-                        // Check return statement to infer type
-                        if (getter.value.body &&
-                            getter.value.body.type === utils_1.AST_NODE_TYPES.BlockStatement) {
-                            const returnStmt = getter.value.body.body.find((stmt) => stmt.type === utils_1.AST_NODE_TYPES.ReturnStatement);
-                            if (returnStmt?.argument?.type === utils_1.AST_NODE_TYPES.MemberExpression) {
-                                return checkMemberExpressionForCollectionReference(returnStmt.argument);
-                            }
-                        }
+                        return yieldsTypedCollectionReference(getter.value);
                     }
                 }
             }
             return false;
         }
+        /**
+         * Guards the return-expression inference below against a class whose
+         * members refer to one another, such as `get a() { return this.a; }` or a
+         * pair of mutually recursive methods. Following the expression is otherwise
+         * unbounded, and a cycle is legal input that must terminate rather than
+         * exhaust the stack.
+         */
+        const inferenceInProgress = new Set();
+        /**
+         * Reports whether a class member provably hands back a typed
+         * CollectionReference.
+         *
+         * The explicit return annotation is authoritative where it exists, but it
+         * cannot be the only evidence read: `no-explicit-return-type` ships in the
+         * same recommended config and is fixable, so a single `eslint --fix` pass
+         * deletes it. The schema the annotation described still lives in the
+         * expression the member returns, and that expression is what the fixer
+         * leaves behind, so it is read as the fallback.
+         */
+        function yieldsTypedCollectionReference(fn) {
+            if (fn.returnType) {
+                return hasCollectionReferenceType(fn.returnType.typeAnnotation);
+            }
+            if (!fn.body || inferenceInProgress.has(fn)) {
+                return false;
+            }
+            inferenceInProgress.add(fn);
+            try {
+                if (fn.body.type !== utils_1.AST_NODE_TYPES.BlockStatement) {
+                    return isTypedCollectionReference(fn.body);
+                }
+                // Only top-level returns are read; a return nested inside another
+                // function belongs to that one.
+                return fn.body.body.some((statement) => statement.type === utils_1.AST_NODE_TYPES.ReturnStatement &&
+                    !!statement.argument &&
+                    isTypedCollectionReference(statement.argument));
+            }
+            finally {
+                inferenceInProgress.delete(fn);
+            }
+        }
         function checkIdentifierForCollectionReference(node) {
             // Check function parameters
             const functionParam = findFunctionParameter(node);
@@ -374,12 +404,9 @@ exports.enforceFirestoreDocRefGeneric = (0, createRule_1.createRule)({
                     if (obj.type === utils_1.AST_NODE_TYPES.ThisExpression) {
                         const classNode = findParentClass(node);
                         if (classNode) {
-                            const method = classNode.body.body.find((member) => member.type === utils_1.AST_NODE_TYPES.MethodDefinition &&
-                                member.key.type === utils_1.AST_NODE_TYPES.Identifier &&
-                                member.key.name === property.name &&
-                                !!member.value.returnType);
-                            if (method?.value.returnType) {
-                                return hasCollectionReferenceType(method.value.returnType.typeAnnotation);
+                            const callee = findClassCallable(classNode, property.name);
+                            if (callee) {
+                                return yieldsTypedCollectionReference(callee);
                             }
                         }
                     }
@@ -387,6 +414,37 @@ exports.enforceFirestoreDocRefGeneric = (0, createRule_1.createRule)({
             }
             return false;
         }
+        /**
+         * Resolves `this.<name>()` to the function the call runs, covering both a
+         * method declaration and a property holding a function expression. The
+         * member is matched by name alone: requiring a return annotation here would
+         * make the resolution disappear the moment `no-explicit-return-type`
+         * strips it, even though the returned expression is unchanged.
+         */
+        function findClassCallable(classNode, name) {
+            for (const member of classNode.body.body) {
+                if (member.type === utils_1.AST_NODE_TYPES.MethodDefinition &&
+                    member.kind === 'method' &&
+                    member.key.type === utils_1.AST_NODE_TYPES.Identifier &&
+                    member.key.name === name) {
+                    return member.value;
+                }
+                if (member.type === utils_1.AST_NODE_TYPES.PropertyDefinition &&
+                    member.key.type === utils_1.AST_NODE_TYPES.Identifier &&
+                    member.key.name === name) {
+                    // An annotated property is already resolved by the member-expression
+                    // path, which reads the annotation rather than the initializer.
+                    if (member.typeAnnotation || !member.value) {
+                        return undefined;
+                    }
+                    const initializer = member.value;
+                    const isFunction = initializer.type === utils_1.AST_NODE_TYPES.ArrowFunctionExpression ||
+                        initializer.type === utils_1.AST_NODE_TYPES.FunctionExpression;
+                    return isFunction ? initializer : undefined;
+                }
+            }
+            return undefined;
+        }
         function getTypeOfMemberExpression(node) {
             if (node.object.type === utils_1.AST_NODE_TYPES.ThisExpression &&
                 node.property.type === utils_1.AST_NODE_TYPES.Identifier) {

package/lib/rules/enforce-verb-noun-naming.js

@@ -3767,6 +3767,154 @@ const ALLOWLIST = {
         'zoom',
     ]),
 };
+/** Higher-order components that only ever wrap another component. */
+const COMPONENT_WRAPPERS = new Set(['memo', 'forwardRef']);
+/** Element factories a component uses when it renders without JSX syntax. */
+const ELEMENT_FACTORIES = new Set(['createElement', 'cloneElement']);
+/** A hook call is named `useX`; a PascalCase caller of one is a component. */
+const HOOK_CALL = /^use[A-Z]/;
+/**
+ * A nested function owns its own returns and its own hook calls, so evidence
+ * gathered about the enclosing function must stop at its boundary.
+ */
+const FUNCTION_LIKE_TYPES = new Set([
+    utils_1.AST_NODE_TYPES.FunctionDeclaration,
+    utils_1.AST_NODE_TYPES.FunctionExpression,
+    utils_1.AST_NODE_TYPES.ArrowFunctionExpression,
+]);
+/**
+ * Visits every descendant of `node` that belongs to the same function scope.
+ * Nested functions are handed to `visit` but not descended into.
+ */
+function forEachNodeInOwnScope(node, visit) {
+    for (const key of Object.keys(node)) {
+        if (key === 'parent') {
+            continue;
+        }
+        const value = node[key];
+        const children = Array.isArray(value) ? value : [value];
+        for (const child of children) {
+            if (!ASTHelpers_1.ASTHelpers.isNode(child)) {
+                continue;
+            }
+            visit(child);
+            if (!FUNCTION_LIKE_TYPES.has(child.type)) {
+                forEachNodeInOwnScope(child, visit);
+            }
+        }
+    }
+}
+/**
+ * The name of a call to `name(...)` or `React.name(...)`. Member calls are
+ * confined to the React namespace so `document.createElement(...)` — an ordinary
+ * DOM call — is not mistaken for a render.
+ */
+function calleeName(callee) {
+    if (callee.type === utils_1.AST_NODE_TYPES.Identifier) {
+        return callee.name;
+    }
+    if (callee.type === utils_1.AST_NODE_TYPES.MemberExpression &&
+        !callee.computed &&
+        callee.object.type === utils_1.AST_NODE_TYPES.Identifier &&
+        callee.object.name === 'React' &&
+        callee.property.type === utils_1.AST_NODE_TYPES.Identifier) {
+        return callee.property.name;
+    }
+    return undefined;
+}
+/** A generator yields values rather than rendering, so it is never a component. */
+function isGeneratorFunction(node) {
+    return node.type !== utils_1.AST_NODE_TYPES.ArrowFunctionExpression && node.generator;
+}
+/**
+ * Whether a returned expression is something React renders. `null`/`undefined`
+ * are the "render nothing" case a component reaches through an early return,
+ * and `createElement` is how a component renders from a file that cannot hold
+ * JSX syntax.
+ */
+function isRenderableValue(value) {
+    if (!value) {
+        return false;
+    }
+    switch (value.type) {
+        case utils_1.AST_NODE_TYPES.Literal:
+            // Matched on `raw` because a regex literal an environment cannot compile
+            // also carries `value === null`.
+            return value.raw === 'null';
+        case utils_1.AST_NODE_TYPES.Identifier:
+            return value.name === 'undefined';
+        case utils_1.AST_NODE_TYPES.JSXElement:
+        case utils_1.AST_NODE_TYPES.JSXFragment:
+            return true;
+        case utils_1.AST_NODE_TYPES.CallExpression: {
+            const name = calleeName(value.callee);
+            return !!name && ELEMENT_FACTORIES.has(name);
+        }
+        case utils_1.AST_NODE_TYPES.TSAsExpression:
+        case utils_1.AST_NODE_TYPES.TSSatisfiesExpression:
+        case utils_1.AST_NODE_TYPES.TSNonNullExpression:
+        case utils_1.AST_NODE_TYPES.TSTypeAssertion:
+            return isRenderableValue(value.expression);
+        case utils_1.AST_NODE_TYPES.ConditionalExpression:
+            // Every branch has to render, otherwise `cond ? value : null` — an
+            // ordinary lookup-with-fallback — would read as a component.
+            return (isRenderableValue(value.consequent) &&
+                isRenderableValue(value.alternate));
+        default:
+            return false;
+    }
+}
+/**
+ * Whether every value the function returns is renderable, and it returns at
+ * least once. Demanding *every* return keeps a helper that merely falls back to
+ * `null` on one branch out of the component exemption, and demanding one return
+ * keeps a function that returns nothing at all out of it.
+ */
+function rendersEveryReturn(node) {
+    if (node.body.type !== utils_1.AST_NODE_TYPES.BlockStatement) {
+        return isRenderableValue(node.body);
+    }
+    const returned = [];
+    forEachNodeInOwnScope(node.body, (child) => {
+        if (child.type === utils_1.AST_NODE_TYPES.ReturnStatement) {
+            returned.push(child.argument);
+        }
+    });
+    return returned.length > 0 && returned.every(isRenderableValue);
+}
+function callsReactHook(node) {
+    let found = false;
+    forEachNodeInOwnScope(node.body, (child) => {
+        if (found || child.type !== utils_1.AST_NODE_TYPES.CallExpression) {
+            return;
+        }
+        const name = calleeName(child.callee);
+        found = !!name && HOOK_CALL.test(name);
+    });
+    return found;
+}
+/**
+ * Whether a reference to the function names it as a component: rendered as a
+ * JSX element, or handed to a higher-order component.
+ */
+function isComponentReference(identifier) {
+    const parent = identifier.parent;
+    if (!parent) {
+        return false;
+    }
+    if (parent.type === utils_1.AST_NODE_TYPES.JSXOpeningElement ||
+        parent.type === utils_1.AST_NODE_TYPES.JSXClosingElement ||
+        parent.type === utils_1.AST_NODE_TYPES.JSXMemberExpression) {
+        return true;
+    }
+    if (parent.type === utils_1.AST_NODE_TYPES.CallExpression) {
+        const name = calleeName(parent.callee);
+        return (!!name &&
+            COMPONENT_WRAPPERS.has(name) &&
+            parent.arguments.some((argument) => argument === identifier));
+    }
+    return false;
+}
 exports.enforceVerbNounNaming = (0, createRule_1.createRule)({
     name: 'enforce-verb-noun-naming',
     meta: {
@@ -3960,6 +4108,19 @@ exports.enforceVerbNounNaming = (0, createRule_1.createRule)({
             }
             return false;
         }
+        /**
+         * Whether the file names the function as a component somewhere other than
+         * its declaration — `<MyComponent />`, `memo(MyComponent)`. Resolved through
+         * scope analysis, which records JSX element names as references.
+         */
+        function isUsedAsReactComponent(node, functionName) {
+            const scope = ASTHelpers_1.ASTHelpers.getScope(context, node);
+            const variable = ASTHelpers_1.ASTHelpers.findVariableInScope(scope, functionName);
+            if (!variable) {
+                return false;
+            }
+            return variable.references.some((reference) => isComponentReference(reference.identifier));
+        }
         function isReactComponent(node) {
             if (node.type !== utils_1.AST_NODE_TYPES.FunctionDeclaration &&
                 node.type !== utils_1.AST_NODE_TYPES.ArrowFunctionExpression &&
@@ -3985,6 +4146,18 @@ exports.enforceVerbNounNaming = (0, createRule_1.createRule)({
                 if (isJsxFile || returnsJsx || hasReactType) {
                     return true;
                 }
+                // The annotation cannot be the only evidence a `.ts` file offers, because
+                // `no-explicit-return-type --fix` — shipped in the same recommended config
+                // — deletes it, leaving a component indistinguishable from a helper and
+                // demanding a rename that would break every JSX call site. A component
+                // is therefore also recognised by what it renders, by the hooks it calls,
+                // and by how the rest of the file uses it.
+                if (!isGeneratorFunction(node) &&
+                    (rendersEveryReturn(node) ||
+                        callsReactHook(node) ||
+                        isUsedAsReactComponent(node, functionName))) {
+                    return true;
+                }
             }
             // If we have explicit React type, still treat it as a component to avoid false naming violations.
             if (hasReactType) {

package/lib/rules/no-explicit-return-type.js

@@ -34,16 +34,22 @@ function describeClassMethod(node) {
     return 'class method';
 }
 function describeMethodSignature(node) {
+    // A method signature is equally non-inferable in either container, but naming
+    // the wrong one sends the reader looking for an `interface` keyword that the
+    // source does not contain.
+    const kind = node.parent?.type === utils_1.AST_NODE_TYPES.TSTypeLiteral
+        ? 'type literal method'
+        : 'interface method';
     if (!node.computed &&
         (node.key.type === utils_1.AST_NODE_TYPES.Identifier ||
             (node.key.type === utils_1.AST_NODE_TYPES.Literal &&
                 typeof node.key.value === 'string'))) {
         const name = getNameFromIdentifierOrLiteral(node.key);
         if (name) {
-            return `interface method "${name}"`;
+            return `${kind} "${name}"`;
         }
     }
-    return 'interface method';
+    return kind;
 }
 function describeFunctionDeclaration(node) {
     if (node.id?.name) {
@@ -449,12 +455,29 @@ function participatesInReturnCycle(name, graph) {
     }
     return false;
 }
+/**
+ * The sibling members of a method signature's container. An interface body and a
+ * type literal declare exactly the same members — `interface X { f(): void }` and
+ * `type X = { f(): void }` differ only in the keyword that introduces them, and
+ * `prefer-type-over-interface` (also fixable, also in the recommended config)
+ * rewrites the first into the second. A member's inferability cannot depend on
+ * which keyword declared its container, so both are read here.
+ */
+function signatureContainerMembers(container) {
+    if (container?.type === utils_1.AST_NODE_TYPES.TSInterfaceBody) {
+        return container.body;
+    }
+    if (container?.type === utils_1.AST_NODE_TYPES.TSTypeLiteral) {
+        return container.members;
+    }
+    return undefined;
+}
 function isOverloadedFunction(node) {
     if (!node.parent)
         return false;
     if (node.type === utils_1.AST_NODE_TYPES.TSMethodSignature) {
-        const interfaceBody = node.parent;
-        if (interfaceBody.type !== utils_1.AST_NODE_TYPES.TSInterfaceBody)
+        const members = signatureContainerMembers(node.parent);
+        if (!members)
             return false;
         if (node.computed)
             return false;
@@ -464,7 +487,7 @@ function isOverloadedFunction(node) {
             : undefined;
         if (!methodName)
             return false;
-        return (interfaceBody.body.filter((member) => member.type === utils_1.AST_NODE_TYPES.TSMethodSignature &&
+        return (members.filter((member) => member.type === utils_1.AST_NODE_TYPES.TSMethodSignature &&
             !member.computed &&
             (member.key.type === utils_1.AST_NODE_TYPES.Identifier ||
                 member.key.type === utils_1.AST_NODE_TYPES.Literal) &&

package/lib/rules/no-unnecessary-verb-suffix.js

@@ -277,6 +277,19 @@ function enclosingFunction(node) {
 function declaresCheckedReturnType(fn) {
     return (fn !== null && checksExcessProperties(fn.returnType?.typeAnnotation ?? null));
 }
+/**
+ * Assertion wrappers, which never change the runtime value they wrap. An
+ * `as const`, `as T`, `satisfies T` or `!` therefore leaves the literal beneath
+ * it the same object, still checked by whatever declared type sits OUTSIDE the
+ * wrapper. Mirrors the set `no-firestore-object-arrays` unwraps for the same
+ * reason.
+ */
+const EXPRESSION_ASSERTION_TYPES = new Set([
+    utils_1.AST_NODE_TYPES.TSAsExpression,
+    utils_1.AST_NODE_TYPES.TSSatisfiesExpression,
+    utils_1.AST_NODE_TYPES.TSNonNullExpression,
+    utils_1.AST_NODE_TYPES.TSTypeAssertion,
+]);
 /**
  * Reports whether `node` sits inside a value whose shape TypeScript checks
  * against a declared type — a type-annotated variable or class field, a
@@ -294,8 +307,13 @@ function declaresCheckedReturnType(fn) {
  * that shape's sole way to declare the contract it imitates.
  *
  * The walk climbs object/array containers so an outer signal covers nested
- * members, and stops at anything else — notably `as` assertions, which do not
- * reject undeclared members the same way.
+ * members, and climbs THROUGH assertion wrappers, which change no runtime value
+ * and so cannot detach a literal from the declared type it is assigned to
+ * (#1597) — `enforce-object-literal-as-const` ships in the same recommended
+ * config and appends `as const` to exactly these literals by `--fix`. An
+ * assertion is transparent, never itself a signal: `{...} as T` still reports,
+ * because an `as` clause does not reject undeclared members the way an
+ * annotation does. The walk stops at anything else.
  */
 function hasConformanceSignal(node) {
     let current = node;
@@ -304,10 +322,19 @@ function hasConformanceSignal(node) {
         if (!parent) {
             return false;
         }
+        // A `satisfies` clause both asserts and checks, so it is answered before
+        // the wrapper is stepped over; an unchecked one (`satisfies any`) proves
+        // nothing on its own and the walk continues past it to the outer context.
+        if (parent.type === utils_1.AST_NODE_TYPES.TSSatisfiesExpression &&
+            parent.expression === current &&
+            checksExcessProperties(parent.typeAnnotation)) {
+            return true;
+        }
+        if (EXPRESSION_ASSERTION_TYPES.has(parent.type)) {
+            current = parent;
+            continue;
+        }
         switch (parent.type) {
-            case utils_1.AST_NODE_TYPES.TSSatisfiesExpression:
-                return (parent.expression === current &&
-                    checksExcessProperties(parent.typeAnnotation));
             case utils_1.AST_NODE_TYPES.VariableDeclarator:
                 return (parent.init === current &&
                     checksExcessProperties(declaredTypeNode(parent.id)));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blumintinc/eslint-plugin-blumint",
-  "version": "1.20.71",
+  "version": "1.20.72",
   "description": "Custom eslint rules for use within BluMint",
   "author": {
     "name": "Brodie McGuire",

package/release-manifest.json

@@ -1,4 +1,42 @@
 [
+  {
+    "version": "1.20.72",
+    "date": "2026-08-02T03:33:22.821Z",
+    "rules": [
+      {
+        "name": "enforce-firestore-doc-ref-generic",
+        "changeType": "fix",
+        "issues": [
+          1595
+        ],
+        "summary": "infer collection schema from the returned expression, not only the annotation (closes #1595)"
+      },
+      {
+        "name": "enforce-verb-noun-naming",
+        "changeType": "fix",
+        "issues": [
+          1596
+        ],
+        "summary": "recognize a React component without its return annotation (closes #1596)"
+      },
+      {
+        "name": "no-explicit-return-type",
+        "changeType": "fix",
+        "issues": [
+          1598
+        ],
+        "summary": "see overload siblings inside a type literal, not only an interface body (closes #1598)"
+      },
+      {
+        "name": "no-unnecessary-verb-suffix",
+        "changeType": "fix",
+        "issues": [
+          1597
+        ],
+        "summary": "climb through assertion wrappers when seeking a conformance signal (closes #1597)"
+      }
+    ]
+  },
   {
     "version": "1.20.71",
     "date": "2026-08-02T01:25:22.489Z",