@blumintinc/eslint-plugin-blumint 1.20.177 → 1.20.178

package/lib/index.js

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

package/lib/rules/enforce-firestore-facade.js

@@ -23,18 +23,43 @@ const CLIENT_BATCH_FACTORY = 'writeBatch';
 // while the admin SDK only exposes the `db.runTransaction(cb)` method, so the
 // callee shape, not the name, decides which SDK a transaction belongs to.
 const TRANSACTION_RUNNER = 'runTransaction';
+// Realtime Database modules. DocSetter/DocSetterTransaction wrap Firestore and
+// have no Realtime Database counterpart, so reporting a RealtimeDB receiver
+// prescribes a remedy that cannot exist. Keying the carve-out on the import
+// source rather than on the bare type name keeps an unrelated local type named
+// `Reference` from silencing a genuine Firestore write.
+const REALTIME_DB_MODULES = new Set([
+    'firebase-admin/database',
+    'firebase/database',
+    '@firebase/database',
+]);
+// Exports of those modules that type a RealtimeDB node reference.
+const REALTIME_DB_REFERENCE_TYPES = new Set(['Reference', 'ThenableReference']);
+// Exports that type the database handle a reference is obtained from.
+const REALTIME_DB_HANDLE_TYPES = new Set(['Database']);
+// The modular accessor that returns a handle, so `getDatabase().ref(...)` is
+// recognized without relying on the receiver being spelled `realtimeDb`.
+const REALTIME_DB_HANDLE_FACTORIES = new Set(['getDatabase']);
 const isMemberExpression = (node) => node.type === utils_1.AST_NODE_TYPES.MemberExpression;
 const isCallExpression = (node) => node.type === utils_1.AST_NODE_TYPES.CallExpression;
 const isIdentifier = (node) => node.type === utils_1.AST_NODE_TYPES.Identifier;
-const unwrapTSAsExpression = (node) => {
-    if (node.type === utils_1.AST_NODE_TYPES.TSAsExpression) {
-        return unwrapTSAsExpression(node.expression);
+// A TS-only wrapper changes the type of an expression, never the receiver it
+// evaluates to, so every shape check has to look through one. Shared by both
+// the Firestore and the RealtimeDB arms so the two cannot drift apart.
+const unwrapTypeWrappers = (node) => {
+    switch (node.type) {
+        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 unwrapTypeWrappers(node.expression);
+        default:
+            return node;
     }
-    return node;
 };
 const getLeftmostIdentifier = (node) => {
     let current = node
-        ? unwrapTSAsExpression(node)
+        ? unwrapTypeWrappers(node)
         : null;
     while (current) {
         if (isIdentifier(current)) {
@@ -104,6 +129,19 @@ exports.enforceFirestoreFacade = (0, createRule_1.createRule)({
     create(context) {
         const realtimeDbRefVariables = new Set();
         const realtimeDbChildVariables = new Set();
+        // Bindings holding a RealtimeDB `Database`, from which `.ref(...)` yields a
+        // RealtimeDB reference regardless of how the handle is spelled.
+        const realtimeDbHandleVariables = new Set();
+        // Local names of RealtimeDB type exports, so a binding is classified by its
+        // declared type rather than by the receiver's spelling. Aliases
+        // (`import type { Reference as RtdbRef }`) are carried by the local name.
+        const realtimeDbReferenceTypeLocals = new Set();
+        const realtimeDbHandleTypeLocals = new Set();
+        // Namespace bindings for a RealtimeDB module (`import * as database`),
+        // which put the same types behind a qualified name.
+        const realtimeDbNamespaceLocals = new Set();
+        // Local names of value exports that return a handle (`getDatabase`).
+        const realtimeDbHandleFactoryLocals = new Set();
         const collectionObjectVariables = new Set();
         const firestoreCollectionVariables = new Set();
         const firestoreDocRefVariables = new Set();
@@ -132,7 +170,7 @@ exports.enforceFirestoreFacade = (0, createRule_1.createRule)({
             clientFirestoreVariables.delete(name);
         };
         const isClientSdkExportReference = (node, exportName, allowUntracedSpelling) => {
-            const callee = unwrapTSAsExpression(node);
+            const callee = unwrapTypeWrappers(node);
             if (isIdentifier(callee)) {
                 if (clientSdkImportedLocals.get(callee.name) === exportName) {
                     return true;
@@ -151,7 +189,7 @@ exports.enforceFirestoreFacade = (0, createRule_1.createRule)({
         };
         // `writeBatch(firestore)` / `fs.writeBatch(firestore)` — client SDK only.
         const isClientBatchFactoryCall = (node) => {
-            const candidate = unwrapTSAsExpression(node);
+            const candidate = unwrapTypeWrappers(node);
             return (isCallExpression(candidate) &&
                 isClientSdkExportReference(candidate.callee, CLIENT_BATCH_FACTORY, true));
         };
@@ -160,7 +198,7 @@ exports.enforceFirestoreFacade = (0, createRule_1.createRule)({
         // could share it, so the binding must be traced back to the SDK.
         const isClientTransactionRunnerCall = (node) => isClientSdkExportReference(node.callee, TRANSACTION_RUNNER, false);
         const recordFirestoreVariable = (varName, expression) => {
-            const target = unwrapTSAsExpression(expression);
+            const target = unwrapTypeWrappers(expression);
             if (target.type === utils_1.AST_NODE_TYPES.ConditionalExpression) {
                 const matchedConsequent = recordFirestoreVariable(varName, target.consequent);
                 const matchedAlternate = recordFirestoreVariable(varName, target.alternate);
@@ -232,7 +270,7 @@ exports.enforceFirestoreFacade = (0, createRule_1.createRule)({
             return false;
         };
         const isFirestoreCollectionCall = (node) => {
-            const candidate = unwrapTSAsExpression(node);
+            const candidate = unwrapTypeWrappers(node);
             if (!isCallExpression(candidate))
                 return false;
             if (!isMemberExpression(candidate.callee))
@@ -243,7 +281,7 @@ exports.enforceFirestoreFacade = (0, createRule_1.createRule)({
             return isFirestoreRoot(candidate.callee.object, firestoreCollectionVariables, firestoreDocRefVariables);
         };
         const isFirestoreDocumentReference = (node) => {
-            const candidate = unwrapTSAsExpression(node);
+            const candidate = unwrapTypeWrappers(node);
             if (!isCallExpression(candidate))
                 return false;
             if (!isMemberExpression(candidate.callee))
@@ -271,10 +309,36 @@ exports.enforceFirestoreFacade = (0, createRule_1.createRule)({
             const varName = node.left.name;
             const right = node.right;
             clearFirestoreTrackingFor(varName);
+            // A RealtimeDB binding declared elsewhere keeps its role: the write it
+            // receives here has no Firestore facade to route through either way.
+            if (registerRealtimeDbValue(varName, right))
+                return;
             recordFirestoreVariable(varName, right);
         };
-        const recordImportBinding = (localName, importedName, isClientSource) => {
-            if (!isClientSource) {
+        // A `null` imported name marks a namespace or default binding, which puts
+        // the module's exports behind a qualifier.
+        const recordRealtimeDbImport = (localName, importedName, source) => {
+            if (!REALTIME_DB_MODULES.has(source))
+                return;
+            if (importedName === null) {
+                realtimeDbNamespaceLocals.add(localName);
+                return;
+            }
+            if (REALTIME_DB_REFERENCE_TYPES.has(importedName)) {
+                realtimeDbReferenceTypeLocals.add(localName);
+                return;
+            }
+            if (REALTIME_DB_HANDLE_TYPES.has(importedName)) {
+                realtimeDbHandleTypeLocals.add(localName);
+                return;
+            }
+            if (REALTIME_DB_HANDLE_FACTORIES.has(importedName)) {
+                realtimeDbHandleFactoryLocals.add(localName);
+            }
+        };
+        const recordImportBinding = (localName, importedName, source) => {
+            recordRealtimeDbImport(localName, importedName, source);
+            if (!CLIENT_SDK_MODULES.has(source)) {
                 nonClientImportedLocals.add(localName);
                 return;
             }
@@ -285,7 +349,6 @@ exports.enforceFirestoreFacade = (0, createRule_1.createRule)({
             clientSdkImportedLocals.set(localName, importedName);
         };
         const recordImportPattern = (pattern, source) => {
-            const isClientSource = CLIENT_SDK_MODULES.has(source);
             if (pattern.type === utils_1.AST_NODE_TYPES.ObjectPattern) {
                 for (const property of pattern.properties) {
                     if (property.type !== utils_1.AST_NODE_TYPES.Property)
@@ -293,16 +356,16 @@ exports.enforceFirestoreFacade = (0, createRule_1.createRule)({
                     if (!isIdentifier(property.key) || !isIdentifier(property.value)) {
                         continue;
                     }
-                    recordImportBinding(property.value.name, property.key.name, isClientSource);
+                    recordImportBinding(property.value.name, property.key.name, source);
                 }
                 return;
             }
             if (isIdentifier(pattern)) {
-                recordImportBinding(pattern.name, null, isClientSource);
+                recordImportBinding(pattern.name, null, source);
             }
         };
         const getImportExpressionSource = (node) => {
-            const expression = unwrapTSAsExpression(node);
+            const expression = unwrapTypeWrappers(node);
             if (expression.type !== utils_1.AST_NODE_TYPES.ImportExpression)
                 return null;
             const source = expression.source;
@@ -324,7 +387,7 @@ exports.enforceFirestoreFacade = (0, createRule_1.createRule)({
             const init = node.init;
             if (!init || init.type !== utils_1.AST_NODE_TYPES.AwaitExpression)
                 return;
-            const awaited = unwrapTSAsExpression(init.argument);
+            const awaited = unwrapTypeWrappers(init.argument);
             const directSource = getImportExpressionSource(awaited);
             if (directSource !== null) {
                 recordImportPattern(node.id, directSource);
@@ -377,59 +440,157 @@ exports.enforceFirestoreFacade = (0, createRule_1.createRule)({
                 firestoreTransactionVariables.add(param.name);
             }
         };
-        const isRealtimeDbRefAssignment = (node) => {
-            if (node.type !== utils_1.AST_NODE_TYPES.VariableDeclarator)
-                return false;
-            const init = node.init;
-            if (!init)
-                return false;
-            if (init.type === utils_1.AST_NODE_TYPES.CallExpression &&
-                isMemberExpression(init.callee) &&
-                isIdentifier(init.callee.property) &&
-                init.callee.property.name === 'ref' &&
-                isIdentifier(init.callee.object) &&
-                (init.callee.object.name === 'realtimeDb' ||
-                    init.callee.object.name.includes('realtimeDb')) &&
-                isIdentifier(node.id)) {
-                realtimeDbRefVariables.add(node.id.name);
+        const classifyRealtimeDbTypeName = (typeName) => {
+            if (isIdentifier(typeName)) {
+                if (realtimeDbReferenceTypeLocals.has(typeName.name)) {
+                    return 'reference';
+                }
+                return realtimeDbHandleTypeLocals.has(typeName.name) ? 'handle' : null;
+            }
+            if (typeName.type === utils_1.AST_NODE_TYPES.TSQualifiedName) {
+                const qualifier = getLeftmostIdentifier(typeName.left);
+                if (!qualifier || !realtimeDbNamespaceLocals.has(qualifier.name)) {
+                    return null;
+                }
+                if (REALTIME_DB_REFERENCE_TYPES.has(typeName.right.name)) {
+                    return 'reference';
+                }
+                return REALTIME_DB_HANDLE_TYPES.has(typeName.right.name)
+                    ? 'handle'
+                    : null;
+            }
+            return null;
+        };
+        // `Reference | null` is the ordinary spelling for a ref held across calls,
+        // so a union member carries the signal just as a bare annotation does.
+        const classifyRealtimeDbType = (typeNode) => {
+            if (typeNode.type === utils_1.AST_NODE_TYPES.TSTypeReference) {
+                return classifyRealtimeDbTypeName(typeNode.typeName);
+            }
+            if (typeNode.type === utils_1.AST_NODE_TYPES.TSUnionType ||
+                typeNode.type === utils_1.AST_NODE_TYPES.TSIntersectionType) {
+                for (const member of typeNode.types) {
+                    const kind = classifyRealtimeDbType(member);
+                    if (kind)
+                        return kind;
+                }
+            }
+            return null;
+        };
+        // An assertion states the author's intent as plainly as an annotation, and
+        // is the shape RealtimeDB refs take at call sites that narrow away `null`.
+        const classifyRealtimeDbAssertion = (node) => {
+            let current = node;
+            for (;;) {
+                if (current.type === utils_1.AST_NODE_TYPES.TSNonNullExpression) {
+                    current = current.expression;
+                    continue;
+                }
+                if (current.type === utils_1.AST_NODE_TYPES.TSAsExpression ||
+                    current.type === utils_1.AST_NODE_TYPES.TSSatisfiesExpression ||
+                    current.type === utils_1.AST_NODE_TYPES.TSTypeAssertion) {
+                    const kind = classifyRealtimeDbType(current.typeAnnotation);
+                    if (kind)
+                        return kind;
+                    current = current.expression;
+                    continue;
+                }
+                return null;
+            }
+        };
+        const registerRealtimeDbBinding = (name, kind) => {
+            if (kind === 'reference') {
+                realtimeDbRefVariables.add(name);
                 return true;
             }
-            if (init.type === utils_1.AST_NODE_TYPES.CallExpression &&
-                isMemberExpression(init.callee) &&
-                isIdentifier(init.callee.property) &&
-                init.callee.property.name === 'child' &&
-                isIdentifier(init.callee.object) &&
-                realtimeDbRefVariables.has(init.callee.object.name) &&
-                isIdentifier(node.id)) {
-                realtimeDbChildVariables.add(node.id.name);
+            if (kind === 'handle') {
+                realtimeDbHandleVariables.add(name);
                 return true;
             }
             return false;
         };
+        const isRealtimeDbHandleFactoryCall = (node) => {
+            const target = unwrapTypeWrappers(node);
+            if (!isCallExpression(target))
+                return false;
+            const callee = target.callee;
+            if (isIdentifier(callee)) {
+                return realtimeDbHandleFactoryLocals.has(callee.name);
+            }
+            return (isMemberExpression(callee) &&
+                isIdentifier(callee.property) &&
+                REALTIME_DB_HANDLE_FACTORIES.has(callee.property.name) &&
+                isIdentifier(callee.object) &&
+                realtimeDbNamespaceLocals.has(callee.object.name));
+        };
+        const isRealtimeDbHandle = (node) => {
+            if (classifyRealtimeDbAssertion(node) === 'handle')
+                return true;
+            if (isRealtimeDbHandleFactoryCall(node))
+                return true;
+            const target = unwrapTypeWrappers(node);
+            return (isIdentifier(target) &&
+                (target.name.includes('realtimeDb') ||
+                    realtimeDbHandleVariables.has(target.name)));
+        };
+        const isRealtimeDbMethodCallOn = (node, method, isRealtimeDbReceiver) => {
+            const target = unwrapTypeWrappers(node);
+            return (isCallExpression(target) &&
+                isMemberExpression(target.callee) &&
+                isIdentifier(target.callee.property) &&
+                target.callee.property.name === method &&
+                isRealtimeDbReceiver(target.callee.object));
+        };
         const isRealtimeDbReference = (node) => {
-            if (node.type === utils_1.AST_NODE_TYPES.CallExpression &&
-                isMemberExpression(node.callee) &&
-                isIdentifier(node.callee.property) &&
-                node.callee.property.name === 'ref' &&
-                isIdentifier(node.callee.object) &&
-                (node.callee.object.name === 'realtimeDb' ||
-                    node.callee.object.name.includes('realtimeDb'))) {
+            if (classifyRealtimeDbAssertion(node) === 'reference')
                 return true;
+            const target = unwrapTypeWrappers(node);
+            if (isIdentifier(target)) {
+                return (realtimeDbRefVariables.has(target.name) ||
+                    realtimeDbChildVariables.has(target.name));
             }
-            if (isIdentifier(node)) {
-                return (realtimeDbRefVariables.has(node.name) ||
-                    realtimeDbChildVariables.has(node.name));
-            }
-            if (node.type === utils_1.AST_NODE_TYPES.CallExpression &&
-                isMemberExpression(node.callee) &&
-                isIdentifier(node.callee.property) &&
-                node.callee.property.name === 'child' &&
-                isIdentifier(node.callee.object) &&
-                (realtimeDbRefVariables.has(node.callee.object.name) ||
-                    realtimeDbChildVariables.has(node.callee.object.name))) {
+            return (isRealtimeDbMethodCallOn(target, 'ref', isRealtimeDbHandle) ||
+                isRealtimeDbMethodCallOn(target, 'child', isRealtimeDbReference));
+        };
+        // Returns the RealtimeDB role a value carries, so the two registration
+        // sites (declarator init and later assignment) share one classification.
+        const classifyRealtimeDbValue = (node) => {
+            const asserted = classifyRealtimeDbAssertion(node);
+            if (asserted)
+                return asserted;
+            if (isRealtimeDbHandleFactoryCall(node))
+                return 'handle';
+            if (isRealtimeDbMethodCallOn(node, 'ref', isRealtimeDbHandle)) {
+                return 'reference';
+            }
+            return isRealtimeDbMethodCallOn(node, 'child', isRealtimeDbReference)
+                ? 'child'
+                : null;
+        };
+        const registerRealtimeDbValue = (name, value) => {
+            const kind = classifyRealtimeDbValue(value);
+            if (kind === 'child') {
+                realtimeDbChildVariables.add(name);
                 return true;
             }
-            return false;
+            return registerRealtimeDbBinding(name, kind);
+        };
+        const isRealtimeDbRefAssignment = (node) => {
+            if (node.type !== utils_1.AST_NODE_TYPES.VariableDeclarator)
+                return false;
+            if (!isIdentifier(node.id))
+                return false;
+            const varName = node.id.name;
+            // Registering from the annotation covers `let ref: Reference | null`,
+            // where the RealtimeDB call arrives later as an assignment rather than as
+            // this declarator's init.
+            const annotation = node.id.typeAnnotation?.typeAnnotation;
+            if (annotation &&
+                registerRealtimeDbBinding(varName, classifyRealtimeDbType(annotation))) {
+                return true;
+            }
+            const init = node.init;
+            return !!init && registerRealtimeDbValue(varName, init);
         };
         const isTrackedFirestoreName = (name) => firestoreDocRefVariables.has(name) ||
             firestoreBatchVariables.has(name) ||
@@ -505,7 +666,7 @@ exports.enforceFirestoreFacade = (0, createRule_1.createRule)({
             }
             let current = object;
             while (current) {
-                const unwrapped = unwrapTSAsExpression(current);
+                const unwrapped = unwrapTypeWrappers(current);
                 if (isCallExpression(unwrapped) &&
                     isMemberExpression(unwrapped.callee) &&
                     isIdentifier(unwrapped.callee.property)) {
@@ -539,16 +700,23 @@ exports.enforceFirestoreFacade = (0, createRule_1.createRule)({
         };
         return {
             ImportDeclaration(node) {
-                const source = node.source.value;
-                const isClientSource = typeof source === 'string' && CLIENT_SDK_MODULES.has(source);
+                const source = typeof node.source.value === 'string' ? node.source.value : '';
                 for (const specifier of node.specifiers) {
                     if (specifier.type === utils_1.AST_NODE_TYPES.ImportSpecifier) {
-                        recordImportBinding(specifier.local.name, specifier.imported.name, isClientSource);
+                        recordImportBinding(specifier.local.name, specifier.imported.name, source);
                         continue;
                     }
-                    recordImportBinding(specifier.local.name, null, isClientSource);
+                    recordImportBinding(specifier.local.name, null, source);
                 }
             },
+            // Parameters and other annotated bindings declare their RealtimeDB role
+            // without ever holding a `ref(...)` call of their own.
+            Identifier(node) {
+                const annotation = node.typeAnnotation?.typeAnnotation;
+                if (!annotation)
+                    return;
+                registerRealtimeDbBinding(node.name, classifyRealtimeDbType(annotation));
+            },
             VariableDeclarator(node) {
                 recordDynamicImportBindings(node);
                 isRealtimeDbRefAssignment(node);

package/package.json

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

package/release-manifest.json

@@ -1,4 +1,18 @@
 [
+  {
+    "version": "1.20.178",
+    "date": "2026-08-26T22:11:53.342Z",
+    "rules": [
+      {
+        "name": "enforce-firestore-facade",
+        "changeType": "fix",
+        "issues": [
+          2149
+        ],
+        "summary": "key the RealtimeDB carve-out on declared type (closes #2149)"
+      }
+    ]
+  },
   {
     "version": "1.20.177",
     "date": "2026-08-26T16:36:01.459Z",