@blumintinc/eslint-plugin-blumint 1.20.45 → 1.20.47

package/lib/index.js

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

package/lib/rules/enforce-snapshot-state-narrowing.js

@@ -61,7 +61,7 @@ exports.enforceSnapshotStateNarrowing = (0, createRule_1.createRule)({
                     guardFunctions: {
                         type: 'array',
                         items: { type: 'string' },
-                        description: 'Canonical type guard function names',
+                        description: 'Type guard function names; the first is the one suggestions call and import',
                     },
                     excludeFiles: {
                         type: 'array',
@@ -70,23 +70,32 @@ exports.enforceSnapshotStateNarrowing = (0, createRule_1.createRule)({
                     },
                     guardImportSource: {
                         type: 'string',
-                        description: 'Module specifier the suggestion imports isSnapshotReady from',
+                        description: 'Module specifier the suggestion imports the guard from',
                     },
                 },
                 additionalProperties: false,
             },
         ],
         messages: {
-            noFalsyCheck: "Do not use boolean coercion on FirestoreSnapshotState<T>. All string states ('idle', 'loading', 'not-found') are truthy, so '{{expression}}' does not behave as intended. Use isSnapshotReady(state) to narrow to T, or compare explicitly (e.g., state === 'loading').",
-            noRawTypeof: "Do not use '{{expression}}' to narrow FirestoreSnapshotState<T> to data. Use isSnapshotReady(state) instead to maintain the abstraction boundary.",
+            // `guard` is the configured canonical guard name, so a consumer who
+            // renames it is not told to call a function their config says does not
+            // exist. Every report and suggestion supplies it.
+            noFalsyCheck: "Do not use boolean coercion on FirestoreSnapshotState<T>. All string states ('idle', 'loading', 'not-found') are truthy, so '{{expression}}' does not behave as intended. Use {{guard}}(state) to narrow to T, or compare explicitly (e.g., state === 'loading').",
+            noRawTypeof: "Do not use '{{expression}}' to narrow FirestoreSnapshotState<T> to data. Use {{guard}}(state) instead to maintain the abstraction boundary.",
         },
     },
     defaultOptions: [{}],
     create(context, [options]) {
         const snapshotHooks = new Set(options?.snapshotHooks ?? DEFAULT_SNAPSHOT_HOOKS);
-        // guardFunctions is accepted in config for documentation and future extensibility
-        // but detection is purely syntactic (by hook source), not by guard function name.
-        void (options?.guardFunctions ?? DEFAULT_GUARD_FUNCTIONS);
+        /**
+         * The name every suggestion calls, resolves in scope, and imports.
+         * `guardFunctions` may list several recognized guards; the first usable one
+         * is canonical. A list that names nothing callable — empty, or holding only
+         * blanks — falls back to the default rather than leaving the suggestion to
+         * emit `undefined(state)` or `(state)`.
+         */
+        const guardName = options?.guardFunctions?.find((name) => name.trim().length > 0) ??
+            DEFAULT_GUARD_FUNCTIONS[0];
         const excludeFiles = options?.excludeFiles ?? [
             'src/types/FirestoreSnapshotState.ts',
         ];
@@ -163,7 +172,7 @@ exports.enforceSnapshotStateNarrowing = (0, createRule_1.createRule)({
          * import, or would collide with an unrelated binding of the same name.
          */
         function resolveGuardBinding(scope) {
-            const variable = utils_1.ASTUtils.findVariable(scope, GUARD_NAME);
+            const variable = utils_1.ASTUtils.findVariable(scope, guardName);
             if (!variable) {
                 return 'missing';
             }
@@ -214,14 +223,14 @@ exports.enforceSnapshotStateNarrowing = (0, createRule_1.createRule)({
             if (reusable) {
                 const namedSpecifiers = reusable.specifiers.filter(isValueImportSpecifier);
                 const lastSpecifier = namedSpecifiers[namedSpecifiers.length - 1];
-                return fixer.insertTextAfter(lastSpecifier, `, ${GUARD_NAME}`);
+                return fixer.insertTextAfter(lastSpecifier, `, ${guardName}`);
             }
             // A namespace or type-only import of the module cannot take a named value
             // specifier, but its path is proof of how this file reaches the module.
             const source = guardDeclarations.length
                 ? String(guardDeclarations[0].source.value)
                 : guardImportSource;
-            const importText = `import { ${GUARD_NAME} } from '${source}';\n`;
+            const importText = `import { ${guardName} } from '${source}';\n`;
             const [firstImport] = declarations;
             if (firstImport) {
                 return fixer.insertTextBefore(firstImport, importText);
@@ -233,7 +242,7 @@ exports.enforceSnapshotStateNarrowing = (0, createRule_1.createRule)({
         }
         /**
          * Builds the single suggestion shared by every report: swap the flagged
-         * expression for its guard-based equivalent and bring `isSnapshotReady` into
+         * expression for its guard-based equivalent and bring the guard into
          * scope. Declines (no suggestion) when the name is already taken by
          * something that is not the guard.
          */
@@ -241,7 +250,7 @@ exports.enforceSnapshotStateNarrowing = (0, createRule_1.createRule)({
             return [
                 {
                     messageId,
-                    data: { expression: replacement },
+                    data: { expression: replacement, guard: guardName },
                     fix(fixer) {
                         const binding = resolveGuardBinding(scope);
                         if (binding === 'conflict') {
@@ -306,8 +315,8 @@ exports.enforceSnapshotStateNarrowing = (0, createRule_1.createRule)({
                         context.report({
                             node,
                             messageId: 'noRawTypeof',
-                            data: { expression: getText(node) },
-                            suggest: guardSuggestion('noRawTypeof', node, `${GUARD_NAME}(${operand.name})`, context.getScope()),
+                            data: { expression: getText(node), guard: guardName },
+                            suggest: guardSuggestion('noRawTypeof', node, `${guardName}(${operand.name})`, context.getScope()),
                         });
                     }
                     // typeof state === 'string' — allowed (narrows to non-data states)
@@ -327,7 +336,7 @@ exports.enforceSnapshotStateNarrowing = (0, createRule_1.createRule)({
             context.report({
                 node,
                 messageId: 'noFalsyCheck',
-                data: { expression },
+                data: { expression, guard: guardName },
                 suggest: guardSuggestion('noFalsyCheck', fixNode, replacement, context.getScope()),
             });
         }
@@ -372,7 +381,7 @@ exports.enforceSnapshotStateNarrowing = (0, createRule_1.createRule)({
                 // stay negated or the suggestion would reverse the control flow.
                 if (argument.type === utils_1.AST_NODE_TYPES.Identifier &&
                     isSnapshotVar(argument)) {
-                    reportFalsyCheck(node, `!${argument.name}`, `!${GUARD_NAME}(${argument.name})`);
+                    reportFalsyCheck(node, `!${argument.name}`, `!${guardName}(${argument.name})`);
                 }
                 // !!state — the argument is another `!` whose argument is the snapshot var.
                 // The double negation is a truthiness coercion, so the guard is positive.
@@ -381,7 +390,7 @@ exports.enforceSnapshotStateNarrowing = (0, createRule_1.createRule)({
                     argument.argument.type === utils_1.AST_NODE_TYPES.Identifier &&
                     isSnapshotVar(argument.argument)) {
                     const varName = argument.argument.name;
-                    reportFalsyCheck(node, `!!${varName}`, `${GUARD_NAME}(${varName})`);
+                    reportFalsyCheck(node, `!!${varName}`, `${guardName}(${varName})`);
                 }
             },
             // IfStatement: if (state) { ... } or if (!state) { ... }
@@ -389,14 +398,14 @@ exports.enforceSnapshotStateNarrowing = (0, createRule_1.createRule)({
             IfStatement(node) {
                 const test = node.test;
                 if (test.type === utils_1.AST_NODE_TYPES.Identifier && isSnapshotVar(test)) {
-                    reportFalsyCheck(test, test.name, `${GUARD_NAME}(${test.name})`);
+                    reportFalsyCheck(test, test.name, `${guardName}(${test.name})`);
                 }
             },
             // ConditionalExpression: state ? a : b
             ConditionalExpression(node) {
                 const test = node.test;
                 if (test.type === utils_1.AST_NODE_TYPES.Identifier && isSnapshotVar(test)) {
-                    reportFalsyCheck(test, test.name, `${GUARD_NAME}(${test.name})`);
+                    reportFalsyCheck(test, test.name, `${guardName}(${test.name})`);
                 }
             },
             // LogicalExpression: state && expr, state || expr
@@ -408,13 +417,13 @@ exports.enforceSnapshotStateNarrowing = (0, createRule_1.createRule)({
                     if (node.operator === '&&') {
                         // `state && expr` guards expr, so swapping the operand for the
                         // guard keeps both the polarity and the narrowing of `state`.
-                        reportFalsyCheck(left, left.name, `${GUARD_NAME}(${left.name})`);
+                        reportFalsyCheck(left, left.name, `${guardName}(${left.name})`);
                         return;
                     }
                     // `state || fallback` evaluates to the state itself when it is
                     // usable, so a bare operand swap would yield `true` instead of the
                     // data. Only the conditional form preserves that value.
-                    const guarded = `${GUARD_NAME}(${left.name}) ? ${left.name} : ${getText(node.right)}`;
+                    const guarded = `${guardName}(${left.name}) ? ${left.name} : ${getText(node.right)}`;
                     reportFalsyCheck(left, left.name, needsParentheses(node) ? `(${guarded})` : guarded, node);
                 }
             },
@@ -432,7 +441,7 @@ exports.enforceSnapshotStateNarrowing = (0, createRule_1.createRule)({
                     node.arguments[0].type === utils_1.AST_NODE_TYPES.Identifier &&
                     isSnapshotVar(node.arguments[0])) {
                     const varName = node.arguments[0].name;
-                    reportFalsyCheck(node, `Boolean(${varName})`, `${GUARD_NAME}(${varName})`);
+                    reportFalsyCheck(node, `Boolean(${varName})`, `${guardName}(${varName})`);
                 }
             },
         };

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

@@ -148,6 +148,306 @@ function isRecursiveFunction(node) {
     checkNode(node.body);
     return hasRecursiveCall;
 }
+const THIS_OWNER = 'this';
+const FUNCTION_NODE_TYPES = new Set([
+    utils_1.AST_NODE_TYPES.FunctionDeclaration,
+    utils_1.AST_NODE_TYPES.FunctionExpression,
+    utils_1.AST_NODE_TYPES.ArrowFunctionExpression,
+]);
+function pushChildren(node, visitorKeys, stack) {
+    for (const key of visitorKeys[node.type] ?? []) {
+        const value = node[key];
+        const children = Array.isArray(value) ? value : [value];
+        for (const child of children) {
+            if (child && typeof child === 'object' && 'type' in child) {
+                stack.push(child);
+            }
+        }
+    }
+}
+/**
+ * Return expressions belonging to `fn` itself: the concise arrow body, or the
+ * arguments of every `return` whose nearest enclosing function is `fn`.
+ * Returns of nested functions belong to those functions, not to `fn`.
+ */
+function collectOwnReturnExpressions(fn, visitorKeys) {
+    if (fn.body.type !== utils_1.AST_NODE_TYPES.BlockStatement) {
+        return [fn.body];
+    }
+    const returnExpressions = [];
+    const stack = [...fn.body.body];
+    while (stack.length > 0) {
+        const current = stack.pop();
+        if (FUNCTION_NODE_TYPES.has(current.type))
+            continue;
+        if (current.type === utils_1.AST_NODE_TYPES.ReturnStatement) {
+            if (current.argument) {
+                returnExpressions.push(current.argument);
+            }
+            continue;
+        }
+        pushChildren(current, visitorKeys, stack);
+    }
+    return returnExpressions;
+}
+/**
+ * Identifiers that name something (object keys, member property names) are not
+ * references to the binding of the same name.
+ */
+function isReferencePosition(node) {
+    const parent = node.parent;
+    if (!parent)
+        return true;
+    if (parent.type === utils_1.AST_NODE_TYPES.MemberExpression &&
+        !parent.computed &&
+        parent.property === node) {
+        return false;
+    }
+    if ((parent.type === utils_1.AST_NODE_TYPES.Property ||
+        parent.type === utils_1.AST_NODE_TYPES.PropertyDefinition ||
+        parent.type === utils_1.AST_NODE_TYPES.MethodDefinition) &&
+        !parent.computed &&
+        parent.key === node) {
+        return false;
+    }
+    return true;
+}
+function ownerMatches(object, owners) {
+    if (object.type === utils_1.AST_NODE_TYPES.ThisExpression) {
+        return owners.has(THIS_OWNER);
+    }
+    if (object.type === utils_1.AST_NODE_TYPES.Identifier) {
+        return owners.has(object.name);
+    }
+    return false;
+}
+/**
+ * Searches a whole expression subtree, nested functions included. A closure in
+ * the returned value is part of the return type, so a self-reference inside it
+ * can be what defeats inference: `return { orderBy: () => buildQuery(p) }
+ * satisfies FakeQuery` is TS7023. Whether TypeScript manages to break such a
+ * cycle depends on type information this rule does not have, so every reference
+ * in a return expression counts — erring toward silence, per the repo's
+ * preference for false negatives over false positives.
+ */
+function subtreeReferences(root, selfReferences, visitorKeys) {
+    const stack = [root];
+    while (stack.length > 0) {
+        const current = stack.pop();
+        if (current.type === utils_1.AST_NODE_TYPES.Identifier &&
+            isReferencePosition(current) &&
+            selfReferences.some((reference) => reference.kind === 'identifier' && reference.name === current.name)) {
+            return true;
+        }
+        if (current.type === utils_1.AST_NODE_TYPES.MemberExpression &&
+            !current.computed &&
+            current.property.type === utils_1.AST_NODE_TYPES.Identifier) {
+            const propertyName = current.property.name;
+            const matchesMember = selfReferences.some((reference) => reference.kind === 'member' &&
+                reference.name === propertyName &&
+                ownerMatches(current.object, reference.owners));
+            if (matchesMember)
+                return true;
+        }
+        pushChildren(current, visitorKeys, stack);
+    }
+    return false;
+}
+function ownerNamesOfObjectExpression(objectExpression) {
+    const owners = new Set([THIS_OWNER]);
+    const parent = objectExpression.parent;
+    if (parent?.type === utils_1.AST_NODE_TYPES.VariableDeclarator &&
+        parent.id.type === utils_1.AST_NODE_TYPES.Identifier) {
+        owners.add(parent.id.name);
+    }
+    return owners;
+}
+function ownerNamesOfClassMember(member) {
+    const owners = new Set([THIS_OWNER]);
+    const classBody = member.parent;
+    const classNode = classBody?.parent;
+    if (classNode?.type === utils_1.AST_NODE_TYPES.ClassDeclaration ||
+        classNode?.type === utils_1.AST_NODE_TYPES.ClassExpression) {
+        if (classNode.id) {
+            owners.add(classNode.id.name);
+        }
+        // A class expression assigned to a binding is also reachable by that name.
+        if (classNode.parent?.type === utils_1.AST_NODE_TYPES.VariableDeclarator &&
+            classNode.parent.id.type === utils_1.AST_NODE_TYPES.Identifier) {
+            owners.add(classNode.parent.id.name);
+        }
+    }
+    return owners;
+}
+function keyName(node) {
+    if (node.computed)
+        return undefined;
+    if (node.key.type === utils_1.AST_NODE_TYPES.Identifier ||
+        (node.key.type === utils_1.AST_NODE_TYPES.Literal &&
+            typeof node.key.value === 'string')) {
+        return getNameFromIdentifierOrLiteral(node.key);
+    }
+    return undefined;
+}
+/**
+ * Every name by which the function can reach itself. A function with no
+ * resolvable name cannot be self-referential by name, so it yields none.
+ */
+function resolveSelfReferences(node) {
+    const selfReferences = [];
+    if (node.type === utils_1.AST_NODE_TYPES.MethodDefinition) {
+        const name = keyName(node);
+        if (name) {
+            selfReferences.push({
+                kind: 'member',
+                name,
+                owners: ownerNamesOfClassMember(node),
+            });
+        }
+        return selfReferences;
+    }
+    if ((node.type === utils_1.AST_NODE_TYPES.FunctionDeclaration ||
+        node.type === utils_1.AST_NODE_TYPES.FunctionExpression) &&
+        node.id) {
+        selfReferences.push({ kind: 'identifier', name: node.id.name });
+    }
+    const parent = node.parent;
+    if (parent?.type === utils_1.AST_NODE_TYPES.VariableDeclarator &&
+        parent.id.type === utils_1.AST_NODE_TYPES.Identifier) {
+        selfReferences.push({ kind: 'identifier', name: parent.id.name });
+    }
+    if (parent?.type === utils_1.AST_NODE_TYPES.Property) {
+        const name = keyName(parent);
+        if (name) {
+            selfReferences.push({
+                kind: 'member',
+                name,
+                owners: ownerNamesOfObjectExpression(parent.parent),
+            });
+        }
+    }
+    if (parent?.type === utils_1.AST_NODE_TYPES.PropertyDefinition) {
+        const name = keyName(parent);
+        if (name) {
+            selfReferences.push({
+                kind: 'member',
+                name,
+                owners: ownerNamesOfClassMember(parent),
+            });
+        }
+    }
+    if (parent?.type === utils_1.AST_NODE_TYPES.AssignmentExpression) {
+        const target = parent.left;
+        if (target.type === utils_1.AST_NODE_TYPES.Identifier) {
+            selfReferences.push({ kind: 'identifier', name: target.name });
+        }
+        else if (target.type === utils_1.AST_NODE_TYPES.MemberExpression &&
+            !target.computed &&
+            target.property.type === utils_1.AST_NODE_TYPES.Identifier) {
+            const owners = new Set();
+            if (target.object.type === utils_1.AST_NODE_TYPES.ThisExpression) {
+                owners.add(THIS_OWNER);
+            }
+            else if (target.object.type === utils_1.AST_NODE_TYPES.Identifier) {
+                owners.add(target.object.name);
+            }
+            if (owners.size > 0) {
+                selfReferences.push({
+                    kind: 'member',
+                    name: target.property.name,
+                    owners,
+                });
+            }
+        }
+    }
+    return selfReferences;
+}
+function bodyOf(node) {
+    if (node.type === utils_1.AST_NODE_TYPES.MethodDefinition) {
+        return node.value.body ? node.value : undefined;
+    }
+    if ((node.type === utils_1.AST_NODE_TYPES.FunctionDeclaration ||
+        node.type === utils_1.AST_NODE_TYPES.FunctionExpression) &&
+        node.body) {
+        return node;
+    }
+    if (node.type === utils_1.AST_NODE_TYPES.ArrowFunctionExpression) {
+        return node;
+    }
+    return undefined;
+}
+/** Bare identifiers referenced from a function's own return expressions. */
+function collectReturnIdentifierNames(fn, visitorKeys) {
+    const names = new Set();
+    for (const returnExpression of collectOwnReturnExpressions(fn, visitorKeys)) {
+        const stack = [returnExpression];
+        while (stack.length > 0) {
+            const current = stack.pop();
+            if (current.type === utils_1.AST_NODE_TYPES.Identifier &&
+                isReferencePosition(current)) {
+                names.add(current.name);
+            }
+            pushChildren(current, visitorKeys, stack);
+        }
+    }
+    return names;
+}
+function moduleScopeFunctions(program) {
+    const functions = new Map();
+    const statements = program.body.map((statement) => {
+        if (statement.type === utils_1.AST_NODE_TYPES.ExportNamedDeclaration ||
+            statement.type === utils_1.AST_NODE_TYPES.ExportDefaultDeclaration) {
+            return statement.declaration ?? statement;
+        }
+        return statement;
+    });
+    for (const statement of statements) {
+        if (statement.type === utils_1.AST_NODE_TYPES.FunctionDeclaration &&
+            statement.id &&
+            statement.body) {
+            functions.set(statement.id.name, statement);
+            continue;
+        }
+        if (statement.type === utils_1.AST_NODE_TYPES.VariableDeclaration) {
+            for (const declarator of statement.declarations) {
+                const init = declarator.init;
+                if (declarator.id.type === utils_1.AST_NODE_TYPES.Identifier &&
+                    init &&
+                    (init.type === utils_1.AST_NODE_TYPES.ArrowFunctionExpression ||
+                        (init.type === utils_1.AST_NODE_TYPES.FunctionExpression && init.body))) {
+                    functions.set(declarator.id.name, init);
+                }
+            }
+        }
+    }
+    return functions;
+}
+/**
+ * Maps each module-scope function name to the names it references from its own
+ * return expressions. A cycle in this graph is mutual recursion, which triggers
+ * the same TS7023 as direct self-reference.
+ */
+function buildReturnReferenceGraph(program, visitorKeys) {
+    const graph = new Map();
+    for (const [name, fn] of moduleScopeFunctions(program)) {
+        graph.set(name, collectReturnIdentifierNames(fn, visitorKeys));
+    }
+    return graph;
+}
+function participatesInReturnCycle(name, graph) {
+    const seen = new Set();
+    const stack = [...(graph.get(name) ?? [])];
+    while (stack.length > 0) {
+        const current = stack.pop();
+        if (current === name)
+            return true;
+        if (seen.has(current))
+            continue;
+        seen.add(current);
+        stack.push(...(graph.get(current) ?? []));
+    }
+    return false;
+}
 function isOverloadedFunction(node) {
     if (!node.parent)
         return false;
@@ -310,6 +610,40 @@ exports.noExplicitReturnType = (0, createRule_1.createRule)({
     create(context, [options]) {
         const mergedOptions = { ...defaultOptions, ...options };
         const filename = context.getFilename();
+        const sourceCode = context.getSourceCode();
+        const visitorKeys = sourceCode.visitorKeys;
+        // Built at most once per file, and only when a direct self-reference has
+        // already been ruled out.
+        let returnReferenceGraph;
+        /**
+         * True when TypeScript cannot infer the return type because the function
+         * is referenced from within its own return expression (TS7023). Removing
+         * the annotation in that case does not compile, so the rule stays silent.
+         */
+        function isReturnTypeRequiredByRecursion(node) {
+            if (!mergedOptions.allowRecursiveFunctions)
+                return false;
+            const fn = bodyOf(node);
+            if (!fn)
+                return false;
+            const selfReferences = resolveSelfReferences(node);
+            if (selfReferences.length === 0)
+                return false;
+            const returnExpressions = collectOwnReturnExpressions(fn, visitorKeys);
+            const referencesItself = returnExpressions.some((expression) => subtreeReferences(expression, selfReferences, visitorKeys));
+            if (referencesItself)
+                return true;
+            const identifierNames = selfReferences
+                .filter((reference) => reference.kind === 'identifier')
+                .map((reference) => reference.name);
+            if (identifierNames.length === 0)
+                return false;
+            if (!returnReferenceGraph) {
+                returnReferenceGraph = buildReturnReferenceGraph(sourceCode.ast, visitorKeys);
+            }
+            const graph = returnReferenceGraph;
+            return identifierNames.some((name) => participatesInReturnCycle(name, graph));
+        }
         if ((mergedOptions.allowDtsFiles && filename.endsWith('.d.ts')) ||
             (mergedOptions.allowFirestoreFunctionFiles &&
                 filename.endsWith('.f.ts'))) {
@@ -333,7 +667,9 @@ exports.noExplicitReturnType = (0, createRule_1.createRule)({
                     return;
                 if (isTypeGuardFunction(node) ||
                     isReadonlyWideningReturnType(returnType) ||
-                    (mergedOptions.allowRecursiveFunctions && isRecursiveFunction(node))) {
+                    (mergedOptions.allowRecursiveFunctions &&
+                        isRecursiveFunction(node)) ||
+                    isReturnTypeRequiredByRecursion(node)) {
                     return;
                 }
                 const isInferable = Boolean(node.body);
@@ -357,7 +693,9 @@ exports.noExplicitReturnType = (0, createRule_1.createRule)({
                 }
                 if (isTypeGuardFunction(node) ||
                     isReadonlyWideningReturnType(returnType) ||
-                    (mergedOptions.allowRecursiveFunctions && isRecursiveFunction(node))) {
+                    (mergedOptions.allowRecursiveFunctions &&
+                        isRecursiveFunction(node)) ||
+                    isReturnTypeRequiredByRecursion(node)) {
                     return;
                 }
                 context.report({
@@ -372,7 +710,8 @@ exports.noExplicitReturnType = (0, createRule_1.createRule)({
                 if (!returnType)
                     return;
                 if (isTypeGuardFunction(node) ||
-                    isReadonlyWideningReturnType(returnType)) {
+                    isReadonlyWideningReturnType(returnType) ||
+                    isReturnTypeRequiredByRecursion(node)) {
                     return;
                 }
                 context.report({
@@ -406,7 +745,8 @@ exports.noExplicitReturnType = (0, createRule_1.createRule)({
                 if (isTypeGuardFunction(node.value) ||
                     isReadonlyWideningReturnType(returnType) ||
                     (mergedOptions.allowAbstractMethodSignatures &&
-                        isInterfaceOrAbstractMethodSignature(node))) {
+                        isInterfaceOrAbstractMethodSignature(node)) ||
+                    isReturnTypeRequiredByRecursion(node)) {
                     return;
                 }
                 const isInferable = Boolean(node.value.body);

package/lib/rules/no-mock-firebase-admin.js

@@ -6,6 +6,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.noMockFirebaseAdmin = void 0;
 const path_1 = __importDefault(require("path"));
 const utils_1 = require("@typescript-eslint/utils");
+const ASTHelpers_1 = require("../utils/ASTHelpers");
 const createRule_1 = require("../utils/createRule");
 const FIREBASE_ADMIN_MODULE = 'firebaseAdmin';
 const MODULE_EXTENSION = /\.(?:tsx?|jsx?|mjs|cjs)$/;
@@ -49,6 +50,72 @@ const bypassesSharedMock = (comparisonPath) => {
     // shared mock.
     return true;
 };
+/**
+ * The one Firestore surface the shared `mockFirestore` fake cannot express: it
+ * seeds collections by path and exposes no `collectionGroup` whatsoever. A suite
+ * that must drive a collection-group query — e.g. the `__name__`-ordered,
+ * index-free `orderBy`/`limit`/`startAfter` pagination loop the migration
+ * scripts run — therefore has no way to obey the message's remedy, and
+ * reporting it demands deleting the assertions the suite exists to make.
+ *
+ * Cursor pagination alone is NOT part of this exemption: `orderBy`, `limit` and
+ * `startAfter` over an ordinary collection are expressible through the shared
+ * fake, so exempting on those would excuse nearly every hand-rolled factory.
+ */
+const COLLECTION_GROUP = 'collectionGroup';
+/**
+ * A string literal only counts where it names a member — an object key or a
+ * computed access — so prose that merely mentions the method (an error message,
+ * a comment-like string) cannot buy an exemption.
+ */
+const namesCollectionGroupLiteral = (node) => {
+    if (node.type === utils_1.AST_NODE_TYPES.Property) {
+        return (node.key.type === utils_1.AST_NODE_TYPES.Literal &&
+            node.key.value === COLLECTION_GROUP);
+    }
+    if (node.type === utils_1.AST_NODE_TYPES.MemberExpression) {
+        return (node.computed &&
+            node.property.type === utils_1.AST_NODE_TYPES.Literal &&
+            node.property.value === COLLECTION_GROUP);
+    }
+    return false;
+};
+/**
+ * Walk the factory for any reference to `collectionGroup`, at any depth: agora's
+ * fake defines it on a returned `db` object, but an equivalent fake may call it
+ * from inside a nested helper or method body.
+ */
+const exercisesCollectionGroup = (factory) => {
+    const stack = [factory];
+    while (stack.length > 0) {
+        const node = stack.pop();
+        if (node.type === utils_1.AST_NODE_TYPES.Identifier &&
+            node.name === COLLECTION_GROUP) {
+            return true;
+        }
+        if (namesCollectionGroupLiteral(node)) {
+            return true;
+        }
+        for (const [key, value] of Object.entries(node)) {
+            // `parent` points back up the tree; following it would walk the whole
+            // program and exempt any file that mentions collectionGroup anywhere.
+            if (key === 'parent') {
+                continue;
+            }
+            if (Array.isArray(value)) {
+                for (const item of value) {
+                    if (ASTHelpers_1.ASTHelpers.isNode(item)) {
+                        stack.push(item);
+                    }
+                }
+            }
+            else if (ASTHelpers_1.ASTHelpers.isNode(value)) {
+                stack.push(value);
+            }
+        }
+    }
+    return false;
+};
 exports.noMockFirebaseAdmin = (0, createRule_1.createRule)({
     name: 'no-mock-firebase-admin',
     meta: {
@@ -101,6 +168,10 @@ exports.noMockFirebaseAdmin = (0, createRule_1.createRule)({
                     if (!bypassesSharedMock(comparisonPathOf(mockPath, filename))) {
                         return;
                     }
+                    const factory = node.arguments[1];
+                    if (factory && exercisesCollectionGroup(factory)) {
+                        return;
+                    }
                     context.report({
                         node,
                         messageId: 'noMockFirebaseAdmin',

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

@@ -248,14 +248,50 @@ function declaredTypeNode(node) {
 function checksExcessProperties(typeNode) {
     return typeNode !== null && !UNCHECKED_ANNOTATION_TYPES.has(typeNode.type);
 }
+function isFunctionNode(node) {
+    return (node.type === utils_1.AST_NODE_TYPES.FunctionDeclaration ||
+        node.type === utils_1.AST_NODE_TYPES.FunctionExpression ||
+        node.type === utils_1.AST_NODE_TYPES.ArrowFunctionExpression);
+}
+/**
+ * The function a `return` statement belongs to — the nearest function ancestor,
+ * which is what the language binds the return to. Scoping to the NEAREST one
+ * keeps a nested callback's literal from inheriting an outer function's
+ * annotation.
+ */
+function enclosingFunction(node) {
+    let current = node.parent;
+    while (current) {
+        if (isFunctionNode(current)) {
+            return current;
+        }
+        current = current.parent;
+    }
+    return null;
+}
+/**
+ * Reports whether `fn` declares a return type that checks the shape of what it
+ * returns. Which type it names is irrelevant — the signal is that the author
+ * declared a contract at all, matching how an annotated variable is treated.
+ */
+function declaresCheckedReturnType(fn) {
+    return (fn !== null && checksExcessProperties(fn.returnType?.typeAnnotation ?? null));
+}
 /**
  * Reports whether `node` sits inside a value whose shape TypeScript checks
- * against a declared type — a type-annotated variable or class field, or a
- * `satisfies` clause. Excess-property checking makes such a literal unable to
- * carry a member the target type does not declare, so a member name there is
- * dictated by that type rather than chosen by the author, and renaming it would
- * break conformance (#1350). No member resolution is needed: the signal alone
- * is proof, because code carrying an undeclared member does not compile.
+ * against a declared type — a type-annotated variable or class field, a
+ * `satisfies` clause, or the return-type annotation of the function that
+ * returns it. Excess-property checking makes such a literal unable to carry a
+ * member the target type does not declare, so a member name there is dictated
+ * by that type rather than chosen by the author, and renaming it would break
+ * conformance (#1350). No member resolution is needed: the signal alone is
+ * proof, because code carrying an undeclared member does not compile.
+ *
+ * The return-type form is the only one a RECURSIVE factory can reach (#1511):
+ * `return {...} satisfies Q` inside a self-referencing factory does not compile
+ * at all (TS7023 — the return type becomes implicitly `any` because the
+ * function is referenced in its own return expression), so the annotation is
+ * 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
@@ -278,6 +314,14 @@ function hasConformanceSignal(node) {
             case utils_1.AST_NODE_TYPES.PropertyDefinition:
                 return (parent.value === current &&
                     checksExcessProperties(declaredTypeNode(parent)));
+            case utils_1.AST_NODE_TYPES.ReturnStatement:
+                // Only the returned value is covered; a literal elsewhere in the body
+                // of an annotated function is unrelated to its declared return type.
+                return (parent.argument === current &&
+                    declaresCheckedReturnType(enclosingFunction(parent)));
+            case utils_1.AST_NODE_TYPES.ArrowFunctionExpression:
+                // A concise arrow body is the returned value.
+                return parent.body === current && declaresCheckedReturnType(parent);
             case utils_1.AST_NODE_TYPES.Property:
             case utils_1.AST_NODE_TYPES.ObjectExpression:
             case utils_1.AST_NODE_TYPES.ArrayExpression:

package/package.json

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

package/release-manifest.json

@@ -1,4 +1,48 @@
 [
+  {
+    "version": "1.20.47",
+    "date": "2026-07-31T08:38:59.580Z",
+    "rules": [
+      {
+        "name": "no-explicit-return-type",
+        "changeType": "fix",
+        "issues": [
+          1512
+        ],
+        "summary": "stop reporting an annotation TypeScript requires (closes #1512)"
+      },
+      {
+        "name": "no-mock-firebase-admin",
+        "changeType": "fix",
+        "issues": [
+          1510
+        ],
+        "summary": "stop reporting factories the shared fake cannot replace (closes #1510)"
+      },
+      {
+        "name": "no-unnecessary-verb-suffix",
+        "changeType": "fix",
+        "issues": [
+          1511
+        ],
+        "summary": "accept a function's own return type as a conformance signal (closes #1511)"
+      }
+    ]
+  },
+  {
+    "version": "1.20.46",
+    "date": "2026-07-31T07:08:55.415Z",
+    "rules": [
+      {
+        "name": "enforce-snapshot-state-narrowing",
+        "changeType": "fix",
+        "issues": [
+          1505
+        ],
+        "summary": "make the guardFunctions option actually select the emitted guard name (closes #1505)"
+      }
+    ]
+  },
   {
     "version": "1.20.45",
     "date": "2026-07-31T06:37:56.216Z",