@blumintinc/eslint-plugin-blumint 1.4.0 → 1.5.0

package/lib/index.js

@@ -50,10 +50,12 @@ const enforce_serializable_params_1 = __importDefault(require("./rules/enforce-s
 const enforce_realtimedb_path_utils_1 = require("./rules/enforce-realtimedb-path-utils");
 const enforce_memoize_async_1 = require("./rules/enforce-memoize-async");
 const enforce_exported_function_types_1 = require("./rules/enforce-exported-function-types");
+const no_redundant_param_types_1 = require("./rules/no-redundant-param-types");
+const no_class_instance_destructuring_1 = require("./rules/no-class-instance-destructuring");
 module.exports = {
     meta: {
         name: '@blumintinc/eslint-plugin-blumint',
-        version: '1.4.0',
+        version: '1.5.0',
     },
     parseOptions: {
         ecmaVersion: 2020,
@@ -109,6 +111,8 @@ module.exports = {
                 '@blumintinc/blumint/enforce-realtimedb-path-utils': 'error',
                 '@blumintinc/blumint/enforce-memoize-async': 'error',
                 '@blumintinc/blumint/enforce-exported-function-types': 'error',
+                '@blumintinc/blumint/no-redundant-param-types': 'error',
+                '@blumintinc/blumint/no-class-instance-destructuring': 'error',
             },
         },
     },
@@ -160,6 +164,8 @@ module.exports = {
         'enforce-realtimedb-path-utils': enforce_realtimedb_path_utils_1.enforceRealtimedbPathUtils,
         'enforce-memoize-async': enforce_memoize_async_1.enforceMemoizeAsync,
         'enforce-exported-function-types': enforce_exported_function_types_1.enforceExportedFunctionTypes,
+        'no-redundant-param-types': no_redundant_param_types_1.noRedundantParamTypes,
+        'no-class-instance-destructuring': no_class_instance_destructuring_1.noClassInstanceDestructuring,
     },
 };
 //# sourceMappingURL=index.js.map

package/lib/rules/array-methods-this-context.js

@@ -55,8 +55,8 @@ exports.arrayMethodsThisContext = (0, createRule_1.createRule)({
         },
         schema: [],
         messages: {
-            unexpected: 'Use an arrow function to preserve "this" context.',
-            preferArrow: 'Use an arrow function instead of binding this.',
+            unexpected: 'Use an arrow function to preserve "this" context in array methods. Instead of `array.map(this.method)`, use `array.map((x) => this.method(x))`.',
+            preferArrow: 'Use an arrow function instead of binding "this". Instead of `array.map(function(x) {}.bind(this))`, use `array.map((x) => {...})`.',
         },
     },
     defaultOptions: [],

package/lib/rules/enforce-callback-memo.js

@@ -7,12 +7,12 @@ exports.default = (0, createRule_1.createRule)({
     meta: {
         type: 'suggestion',
         docs: {
-            description: 'Enforce useCallback or useMemo for inline functions in JSX props',
+            description: 'Enforce useCallback for inline functions and useMemo for objects/arrays containing functions in JSX props to prevent unnecessary re-renders. This improves React component performance by ensuring stable function references across renders and memoizing complex objects.',
             recommended: 'error',
         },
         messages: {
-            enforceCallback: 'Inline functions in JSX props should be wrapped with useCallback',
-            enforceMemo: 'Objects/arrays containing functions in JSX props should be wrapped with useMemo',
+            enforceCallback: 'Inline functions in JSX props should be wrapped with useCallback to prevent unnecessary re-renders. Instead of `<Button onClick={() => handleClick(id)} />`, use `<Button onClick={useCallback(() => handleClick(id), [id])} />`.',
+            enforceMemo: 'Objects/arrays containing functions in JSX props should be wrapped with useMemo to prevent unnecessary re-renders. Instead of `<Component config={{ onSubmit: () => {...} }} />`, use `<Component config={useMemo(() => ({ onSubmit: () => {...} }), [])} />`.',
         },
         schema: [],
     },

package/lib/rules/enforce-dynamic-firebase-imports.js

@@ -7,12 +7,12 @@ exports.enforceFirebaseImports = (0, createRule_1.createRule)({
     meta: {
         type: 'problem',
         docs: {
-            description: 'Enforce dynamic importing for modules within the firebaseCloud directory',
+            description: 'Enforce dynamic importing for modules within the firebaseCloud directory to optimize initial bundle size. This ensures Firebase-related code is only loaded when needed, improving application startup time and reducing the main bundle size.',
             recommended: 'error',
         },
         schema: [],
         messages: {
-            noDynamicImport: 'Static imports from firebaseCloud directory are not allowed. Use dynamic imports instead.',
+            noDynamicImport: 'Static imports from firebaseCloud directory are not allowed to reduce initial bundle size. Instead of `import { func } from "./firebaseCloud/module"`, use dynamic import: `const { func } = await import("./firebaseCloud/module")`.',
         },
     },
     defaultOptions: [],

package/lib/rules/enforce-exported-function-types.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.enforceExportedFunctionTypes = void 0;
+/* eslint-disable @typescript-eslint/no-empty-function */
 const utils_1 = require("@typescript-eslint/utils");
 const createRule_1 = require("../utils/createRule");
 exports.enforceExportedFunctionTypes = (0, createRule_1.createRule)({
@@ -13,9 +14,9 @@ exports.enforceExportedFunctionTypes = (0, createRule_1.createRule)({
         },
         schema: [],
         messages: {
-            missingExportedType: 'Type {{typeName}} should be exported since it is used in an exported function',
-            missingExportedReturnType: 'Return type {{typeName}} should be exported since it is used in an exported function',
-            missingExportedPropsType: 'Props type {{typeName}} should be exported since it is used in an exported React component',
+            missingExportedType: 'Type {{typeName}} should be exported since it is used in an exported function. Add `export` before the type definition: `export type {{typeName}} = ...`',
+            missingExportedReturnType: 'Return type {{typeName}} should be exported since it is used in an exported function. Add `export` before the type definition: `export type {{typeName}} = ...`',
+            missingExportedPropsType: 'Props type {{typeName}} should be exported since it is used in an exported React component. Add `export` before the type definition: `export type {{typeName}} = ...`',
         },
     },
     defaultOptions: [],
@@ -33,30 +34,95 @@ exports.enforceExportedFunctionTypes = (0, createRule_1.createRule)({
                 return false;
             if (parent.type === utils_1.AST_NODE_TYPES.ExportNamedDeclaration ||
                 parent.type === utils_1.AST_NODE_TYPES.ExportDefaultDeclaration ||
-                parent.type === utils_1.AST_NODE_TYPES.VariableDeclarator && isExported(parent.parent)) {
+                (parent.type === utils_1.AST_NODE_TYPES.VariableDeclarator &&
+                    isExported(parent.parent))) {
                 return true;
             }
             return false;
         }
-        function getTypeName(node) {
+        function getTypeNames(node) {
             if (!node)
-                return undefined;
+                return [];
             switch (node.type) {
                 case utils_1.AST_NODE_TYPES.TSTypeReference:
                     if (node.typeName.type === utils_1.AST_NODE_TYPES.Identifier) {
-                        return node.typeName.name;
+                        const names = [node.typeName.name];
+                        // For generic types like AuthenticatedRequest<Params>, check both the base type and type parameters
+                        if ('typeParameters' in node && node.typeParameters) {
+                            node.typeParameters.params.forEach((param) => {
+                                names.push(...getTypeNames(param));
+                            });
+                        }
+                        return names;
                     }
                     break;
                 case utils_1.AST_NODE_TYPES.TSTypeLiteral:
-                    return 'AnonymousType';
+                    return ['AnonymousType'];
+            }
+            return [];
+        }
+        function isBuiltInType(typeName) {
+            const builtInTypes = new Set([
+                'string',
+                'number',
+                'boolean',
+                'null',
+                'undefined',
+                'void',
+                'any',
+                'never',
+                'unknown',
+                'object',
+                'Date',
+                'RegExp',
+                'Error',
+                'Promise',
+                'Array',
+                'Function',
+                'Symbol',
+                'BigInt',
+                'Map',
+                'Set',
+                'WeakMap',
+                'WeakSet',
+            ]);
+            return builtInTypes.has(typeName);
+        }
+        function checkAndReportType(node, parentNode, messageId) {
+            const typeNames = getTypeNames(node);
+            for (const typeName of typeNames) {
+                if (typeName !== 'AnonymousType' &&
+                    !isBuiltInType(typeName) &&
+                    !isTypeExported(typeName)) {
+                    // Check if we've already reported this type
+                    const key = `${typeName}-${parentNode.loc?.start.line}-${parentNode.loc?.start.column}`;
+                    if (!reportedTypes.has(key)) {
+                        reportedTypes.add(key);
+                        context.report({
+                            node: parentNode,
+                            messageId,
+                            data: { typeName },
+                        });
+                    }
+                }
             }
-            return undefined;
         }
         function isTypeExported(typeName) {
             const sourceCode = context.getSourceCode();
             const program = sourceCode.ast;
+            // Check for imported types
+            const importedTypes = program.body.filter((node) => {
+                if (node.type === utils_1.AST_NODE_TYPES.ImportDeclaration) {
+                    return node.specifiers.some((specifier) => specifier.type === utils_1.AST_NODE_TYPES.ImportSpecifier &&
+                        specifier.local.name === typeName);
+                }
+                return false;
+            });
+            if (importedTypes.length > 0) {
+                return true;
+            }
             // Check for exported type declarations
-            const exportedTypes = program.body.filter(node => {
+            const exportedTypes = program.body.filter((node) => {
                 if (node.type === utils_1.AST_NODE_TYPES.ExportNamedDeclaration) {
                     if (node.declaration?.type === utils_1.AST_NODE_TYPES.TSTypeAliasDeclaration) {
                         return node.declaration.id.name === typeName;
@@ -72,7 +138,7 @@ exports.enforceExportedFunctionTypes = (0, createRule_1.createRule)({
             }
             // Check for type aliases in the current scope
             const scope = context.getScope();
-            const variable = scope.variables.find(v => v.name === typeName);
+            const variable = scope.variables.find((v) => v.name === typeName);
             if (!variable)
                 return false;
             const def = variable.defs[0];
@@ -112,36 +178,13 @@ exports.enforceExportedFunctionTypes = (0, createRule_1.createRule)({
                     return;
                 // Check return type
                 if (node.returnType?.typeAnnotation) {
-                    const typeName = getTypeName(node.returnType.typeAnnotation);
-                    if (typeName && !isTypeExported(typeName)) {
-                        // Check if we've already reported this type
-                        const key = `${typeName}-${node.loc?.start.line}-${node.loc?.start.column}`;
-                        if (!reportedTypes.has(key)) {
-                            reportedTypes.add(key);
-                            context.report({
-                                node: node.returnType,
-                                messageId: 'missingExportedReturnType',
-                                data: { typeName },
-                            });
-                        }
-                    }
+                    checkAndReportType(node.returnType.typeAnnotation, node.returnType, 'missingExportedReturnType');
                 }
                 // Check parameter types
-                node.params.forEach(param => {
-                    if (param.type === utils_1.AST_NODE_TYPES.Identifier && param.typeAnnotation) {
-                        const typeName = getTypeName(param.typeAnnotation.typeAnnotation);
-                        if (typeName && !isTypeExported(typeName)) {
-                            // Check if we've already reported this type
-                            const key = `${typeName}-${param.loc?.start.line}-${param.loc?.start.column}`;
-                            if (!reportedTypes.has(key)) {
-                                reportedTypes.add(key);
-                                context.report({
-                                    node: param.typeAnnotation,
-                                    messageId: 'missingExportedType',
-                                    data: { typeName },
-                                });
-                            }
-                        }
+                node.params.forEach((param) => {
+                    if (param.type === utils_1.AST_NODE_TYPES.Identifier &&
+                        param.typeAnnotation) {
+                        checkAndReportType(param.typeAnnotation.typeAnnotation, param.typeAnnotation, 'missingExportedType');
                     }
                 });
             },
@@ -155,36 +198,13 @@ exports.enforceExportedFunctionTypes = (0, createRule_1.createRule)({
                     return;
                 // Check return type
                 if (node.returnType?.typeAnnotation) {
-                    const typeName = getTypeName(node.returnType.typeAnnotation);
-                    if (typeName && !isTypeExported(typeName)) {
-                        // Check if we've already reported this type
-                        const key = `${typeName}-${node.loc?.start.line}-${node.loc?.start.column}`;
-                        if (!reportedTypes.has(key)) {
-                            reportedTypes.add(key);
-                            context.report({
-                                node: node.returnType,
-                                messageId: 'missingExportedReturnType',
-                                data: { typeName },
-                            });
-                        }
-                    }
+                    checkAndReportType(node.returnType.typeAnnotation, node.returnType, 'missingExportedReturnType');
                 }
                 // Check parameter types
-                node.params.forEach(param => {
-                    if (param.type === utils_1.AST_NODE_TYPES.Identifier && param.typeAnnotation) {
-                        const typeName = getTypeName(param.typeAnnotation.typeAnnotation);
-                        if (typeName && !isTypeExported(typeName)) {
-                            // Check if we've already reported this type
-                            const key = `${typeName}-${param.loc?.start.line}-${param.loc?.start.column}`;
-                            if (!reportedTypes.has(key)) {
-                                reportedTypes.add(key);
-                                context.report({
-                                    node: param.typeAnnotation,
-                                    messageId: 'missingExportedType',
-                                    data: { typeName },
-                                });
-                            }
-                        }
+                node.params.forEach((param) => {
+                    if (param.type === utils_1.AST_NODE_TYPES.Identifier &&
+                        param.typeAnnotation) {
+                        checkAndReportType(param.typeAnnotation.typeAnnotation, param.typeAnnotation, 'missingExportedType');
                     }
                 });
             },
@@ -194,20 +214,7 @@ exports.enforceExportedFunctionTypes = (0, createRule_1.createRule)({
                     return;
                 // Check props parameter
                 if (node.typeAnnotation) {
-                    const typeName = getTypeName(node.typeAnnotation.typeAnnotation);
-                    if (typeName && !isTypeExported(typeName)) {
-                        // Check if we've already reported this type
-                        const key = `${typeName}-${node.loc?.start.line}-${node.loc?.start.column}`;
-                        if (!reportedTypes.has(key)) {
-                            reportedTypes.add(key);
-                            context.report({
-                                node: node.typeAnnotation,
-                                messageId: 'missingExportedType',
-                                data: { typeName },
-                            });
-                            return;
-                        }
-                    }
+                    checkAndReportType(node.typeAnnotation.typeAnnotation, node.typeAnnotation, 'missingExportedPropsType');
                 }
             },
             // Skip type checking for React components since we handle them separately
@@ -239,10 +246,6 @@ exports.enforceExportedFunctionTypes = (0, createRule_1.createRule)({
             'VariableDeclarator[id.name=/^[A-Z]/] > ArrowFunctionExpression > Identifier[typeAnnotation] > TSTypeAnnotation > TSTypeReference > TSQualifiedName > TSQualifiedName > TSQualifiedName > TSQualifiedName > Identifier'() { },
             'FunctionDeclaration[id.name=/^[A-Z]/] > Identifier[typeAnnotation] > TSTypeAnnotation > TSTypeReference > TSQualifiedName > TSQualifiedName > TSQualifiedName > TSQualifiedName > TSQualifiedName'() { },
             'VariableDeclarator[id.name=/^[A-Z]/] > ArrowFunctionExpression > Identifier[typeAnnotation] > TSTypeAnnotation > TSTypeReference > TSQualifiedName > TSQualifiedName > TSQualifiedName > TSQualifiedName > TSQualifiedName'() { },
-            'FunctionDeclaration[id.name=/^[A-Z]/] > Identifier[typeAnnotation] > TSTypeAnnotation > TSTypeReference > TSQualifiedName > TSQualifiedName > TSQualifiedName > TSQualifiedName > TSQualifiedName > Identifier'() { },
-            'VariableDeclarator[id.name=/^[A-Z]/] > ArrowFunctionExpression > Identifier[typeAnnotation] > TSTypeAnnotation > TSTypeReference > TSQualifiedName > TSQualifiedName > TSQualifiedName > TSQualifiedName > TSQualifiedName > Identifier'() { },
-            'FunctionDeclaration[id.name=/^[A-Z]/] > Identifier[typeAnnotation] > TSTypeAnnotation > TSTypeReference > TSQualifiedName > TSQualifiedName > TSQualifiedName > TSQualifiedName > TSQualifiedName > TSQualifiedName'() { },
-            'VariableDeclarator[id.name=/^[A-Z]/] > ArrowFunctionExpression > Identifier[typeAnnotation] > TSTypeAnnotation > TSTypeReference > TSQualifiedName > TSQualifiedName > TSQualifiedName > TSQualifiedName > TSQualifiedName > TSQualifiedName'() { },
         };
     },
 });

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

@@ -24,8 +24,8 @@ exports.enforceFirestoreDocRefGeneric = (0, createRule_1.createRule)({
         },
         schema: [],
         messages: {
-            missingGeneric: '{{ type }} must specify a generic type argument',
-            invalidGeneric: '{{ type }} must not use "any" or "{}" as generic type argument',
+            missingGeneric: '{{ type }} must specify a generic type argument for type safety. Instead of `const docRef = doc(collection)`, use `const docRef = doc<YourType>(collection)`.',
+            invalidGeneric: '{{ type }} must not use "any" or "{}" as generic type argument. Define a proper interface/type for your document: `interface UserDoc { name: string; age: number; }` and use it: `const docRef = doc<UserDoc>(collection)`.',
         },
     },
     defaultOptions: [],

package/lib/rules/enforce-firestore-path-utils.js

@@ -9,12 +9,12 @@ exports.enforceFirestorePathUtils = (0, createRule_1.createRule)({
     meta: {
         type: 'suggestion',
         docs: {
-            description: 'Enforce usage of utility functions for Firestore paths',
+            description: 'Enforce usage of utility functions for Firestore paths to ensure type safety, maintainability, and consistent path construction. This prevents errors from manual string concatenation and makes path changes easier to manage.',
             recommended: 'error',
         },
         schema: [],
         messages: {
-            requirePathUtil: 'Use a utility function (e.g., toUserPath, toCollectionPath) for Firestore paths instead of string literals',
+            requirePathUtil: 'Use a utility function for Firestore paths to ensure type safety and maintainability. Instead of `doc("users/" + userId)`, create and use a utility function: `const toUserPath = (id: string) => `users/${id}`; doc(toUserPath(userId))`.',
         },
     },
     defaultOptions: [],

package/lib/rules/enforce-firestore-set-merge.js

@@ -8,7 +8,7 @@ exports.enforceFirestoreSetMerge = (0, createRule_1.createRule)({
     meta: {
         type: 'suggestion',
         docs: {
-            description: 'Enforce using set() with { merge: true } instead of update() for Firestore operations',
+            description: 'Enforce using set() with { merge: true } instead of update() for Firestore operations to ensure consistent behavior. The update() method fails if the document does not exist, while set() with { merge: true } creates the document if needed and safely merges fields, making it more reliable and predictable.',
             recommended: 'error',
             requiresTypeChecking: false,
             extendsBaseRule: false,
@@ -16,19 +16,50 @@ exports.enforceFirestoreSetMerge = (0, createRule_1.createRule)({
         fixable: 'code',
         schema: [],
         messages: {
-            preferSetMerge: 'Use set() with { merge: true } instead of update() for more predictable Firestore operations',
+            preferSetMerge: 'Use set() with { merge: true } instead of update() for more predictable Firestore operations. Instead of `docRef.update({ field: value })`, use `docRef.set({ field: value }, { merge: true })`. This ensures consistent behavior when the document does not exist.',
         },
     },
     defaultOptions: [],
     create(context) {
         const updateAliases = new Set();
         function isFirestoreUpdateCall(node) {
+            // Check if it's a set() call with merge: true
             if (node.callee.type === utils_1.AST_NODE_TYPES.MemberExpression) {
                 const property = node.callee.property;
-                return (property.type === utils_1.AST_NODE_TYPES.Identifier &&
-                    property.name === 'update');
+                if (property.type === utils_1.AST_NODE_TYPES.Identifier) {
+                    // If it's a set() call, check if it has merge: true
+                    if (property.name === 'set') {
+                        const lastArg = node.arguments[node.arguments.length - 1];
+                        if (lastArg?.type === utils_1.AST_NODE_TYPES.ObjectExpression) {
+                            const hasMergeTrue = lastArg.properties.some((prop) => prop.type === utils_1.AST_NODE_TYPES.Property &&
+                                prop.key.type === utils_1.AST_NODE_TYPES.Identifier &&
+                                prop.key.name === 'merge' &&
+                                prop.value.type === utils_1.AST_NODE_TYPES.Literal &&
+                                prop.value.value === true);
+                            if (hasMergeTrue) {
+                                return false; // Already using set with merge: true
+                            }
+                        }
+                    }
+                    // Only flag update() calls
+                    return property.name === 'update';
+                }
             }
             if (node.callee.type === utils_1.AST_NODE_TYPES.Identifier) {
+                // Check if it's a setDoc() call with merge: true
+                if (node.callee.name === 'setDoc') {
+                    const lastArg = node.arguments[node.arguments.length - 1];
+                    if (lastArg?.type === utils_1.AST_NODE_TYPES.ObjectExpression) {
+                        const hasMergeTrue = lastArg.properties.some((prop) => prop.type === utils_1.AST_NODE_TYPES.Property &&
+                            prop.key.type === utils_1.AST_NODE_TYPES.Identifier &&
+                            prop.key.name === 'merge' &&
+                            prop.value.type === utils_1.AST_NODE_TYPES.Literal &&
+                            prop.value.value === true);
+                        if (hasMergeTrue) {
+                            return false; // Already using setDoc with merge: true
+                        }
+                    }
+                }
                 return updateAliases.has(node.callee.name);
             }
             return false;

package/lib/rules/enforce-identifiable-firestore-type.js

@@ -17,8 +17,8 @@ exports.enforceIdentifiableFirestoreType = (0, createRule_1.createRule)({
         },
         schema: [],
         messages: {
-            missingType: 'Expected exported type "{{ typeName }}" in index.ts under folder "{{ folderName }}"',
-            notExtendingIdentifiable: 'Type "{{ typeName }}" must extend "Identifiable", including an "id: string" field',
+            missingType: 'Expected exported type "{{ typeName }}" in index.ts under folder "{{ folderName }}". Create a type that matches the folder name: `export type {{ typeName }} = { /* fields */ }`.',
+            notExtendingIdentifiable: 'Type "{{ typeName }}" must extend "Identifiable" to ensure all Firestore documents have an ID field. Add `extends Identifiable` or include `id: string`: `export type {{ typeName }} = { id: string; /* other fields */ }`.',
         },
     },
     defaultOptions: [],

package/lib/rules/enforce-memoize-async.js

@@ -8,13 +8,13 @@ exports.enforceMemoizeAsync = (0, createRule_1.createRule)({
     meta: {
         type: 'suggestion',
         docs: {
-            description: 'Enforce @Memoize() decorator on async methods with 0-1 parameters',
+            description: 'Enforce @Memoize() decorator on async methods with 0-1 parameters to cache results and prevent redundant API calls or expensive computations. This improves performance by reusing previous results when the same parameters are provided, particularly useful for data fetching methods.',
             recommended: 'error',
         },
         fixable: 'code',
         schema: [],
         messages: {
-            requireMemoize: 'Async methods with 0-1 parameters should be decorated with @Memoize()',
+            requireMemoize: 'Async methods with 0-1 parameters should be decorated with @Memoize() to cache results and improve performance. Instead of `async getData(id?: string)`, use `@Memoize()\nasync getData(id?: string)`. Import Memoize from "typescript-memoize".',
         },
     },
     defaultOptions: [],

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

@@ -13,13 +13,13 @@ exports.enforceFirestoreMock = (0, createRule_1.createRule)({
     meta: {
         type: 'problem',
         docs: {
-            description: 'Enforce using mockFirestore over manual Firestore mocking',
+            description: 'Enforce using the standardized mockFirestore utility instead of manual Firestore mocking or third-party mocks. This ensures consistent test behavior across the codebase, reduces boilerplate, and provides type-safe mocking of Firestore operations.',
             recommended: 'error',
         },
         schema: [],
         messages: {
-            noManualFirestoreMock: 'Use mockFirestore from __mocks__/functions/src/config/mockFirestore instead of manually mocking Firestore',
-            noMockFirebase: 'Use mockFirestore from __mocks__/functions/src/config/mockFirestore instead of mockFirebase',
+            noManualFirestoreMock: 'Use mockFirestore from __mocks__/functions/src/config/mockFirestore instead of manually mocking Firestore. Replace `jest.mock("firebase-admin", () => ({ firestore: () => ({ /* mock */ }) }))` with `import { mockFirestore } from "__mocks__/functions/src/config/mockFirestore"; jest.mock("firebase-admin", () => mockFirestore)`.',
+            noMockFirebase: 'Use mockFirestore from __mocks__/functions/src/config/mockFirestore instead of mockFirebase. Replace `import { mockFirebase } from "firestore-jest-mock"` with `import { mockFirestore } from "__mocks__/functions/src/config/mockFirestore"`.',
         },
     },
     defaultOptions: [],

package/lib/rules/enforce-realtimedb-path-utils.js

@@ -14,7 +14,7 @@ exports.enforceRealtimedbPathUtils = (0, createRule_1.createRule)({
         },
         schema: [],
         messages: {
-            requirePathUtil: 'Use a utility function (e.g., toUserPath, toItemPath) for Realtime Database paths instead of string literals',
+            requirePathUtil: 'Use a utility function for Realtime Database paths to ensure type safety and maintainability. Instead of `ref("users/" + userId)`, create and use a utility function: `const toUserPath = (id: string) => `users/${id}`; ref(toUserPath(userId))`.',
         },
     },
     defaultOptions: [],

package/lib/rules/enforce-safe-stringify.js

@@ -8,13 +8,13 @@ exports.enforceStableStringify = (0, createRule_1.createRule)({
     meta: {
         type: 'problem',
         docs: {
-            description: 'Enforce using safe-stable-stringify instead of JSON.stringify',
+            description: 'Enforce using safe-stable-stringify instead of JSON.stringify to handle circular references and ensure deterministic output. JSON.stringify can throw errors on circular references and produce inconsistent output for objects with the same properties in different orders. safe-stable-stringify handles these cases safely.',
             recommended: 'error',
         },
         fixable: 'code',
         schema: [],
         messages: {
-            useStableStringify: 'Use safe-stable-stringify instead of JSON.stringify for safer serialization',
+            useStableStringify: 'Use safe-stable-stringify instead of JSON.stringify for safer serialization. Replace `JSON.stringify(obj)` with `stringify(obj)`. First import it: `import stringify from "safe-stable-stringify"`. This handles circular references and provides deterministic output.',
         },
     },
     defaultOptions: [],

package/lib/rules/enforce-serializable-params.js

@@ -17,7 +17,7 @@ exports.default = (0, createRule_1.createRule)({
     meta: {
         type: 'problem',
         docs: {
-            description: 'Enforce serializable parameters in Firebase Callable/HTTPS Cloud Functions',
+            description: 'Enforce serializable parameters in Firebase Callable/HTTPS Cloud Functions to prevent runtime errors. Firebase Functions can only pass JSON-serializable data, so using non-serializable types like Date, DocumentReference, or Map will cause failures. Use primitive types, plain objects, and arrays instead, converting complex types to their serializable representations (e.g., Date to ISO string).',
             recommended: 'error',
         },
         schema: [
@@ -38,8 +38,8 @@ exports.default = (0, createRule_1.createRule)({
             },
         ],
         messages: {
-            nonSerializableParam: 'Parameter type "{{ type }}" is not serializable',
-            nonSerializableProperty: 'Property "{{ prop }}" has non-serializable type "{{ type }}"',
+            nonSerializableParam: 'Parameter type "{{ type }}" is not serializable in Firebase Cloud Functions. Use JSON-serializable types like string, number, boolean, arrays, or plain objects. Instead of `Date`, use ISO strings: `new Date().toISOString()`.',
+            nonSerializableProperty: 'Property "{{ prop }}" has non-serializable type "{{ type }}". Use JSON-serializable types. For example, instead of `{ timestamp: Date }`, use `{ timestamp: string }` with ISO format.',
         },
     },
     defaultOptions: [

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

@@ -8,6 +8,22 @@ const utils_1 = require("@typescript-eslint/utils");
 const createRule_1 = require("../utils/createRule");
 const compromise_1 = __importDefault(require("compromise"));
 const PREPOSITIONS = ['to', 'from', 'with', 'by', 'at', 'of'];
+// Common short verbs that should be allowed
+const COMMON_VERBS = new Set([
+    'sync',
+    'fix',
+    'set',
+    'log',
+    'get',
+    'put',
+    'add',
+    'map',
+    'run',
+    'use',
+    'has',
+    'is',
+    'do',
+]);
 exports.enforceVerbNounNaming = (0, createRule_1.createRule)({
     name: 'enforce-verb-noun-naming',
     meta: {
@@ -32,7 +48,8 @@ exports.enforceVerbNounNaming = (0, createRule_1.createRule)({
             return firstChar + words[0];
         }
         function toSentence(name) {
-            return name.split(/(?=[A-Z])/).join(' ');
+            // Add "I" prefix to create a proper sentence for better verb detection
+            return 'I ' + name.split(/(?=[A-Z])/).join(' ');
         }
         function getPossibleTags(sentence) {
             const doc = (0, compromise_1.default)(sentence);
@@ -45,14 +62,23 @@ exports.enforceVerbNounNaming = (0, createRule_1.createRule)({
         function isVerbPhrase(name) {
             const firstWord = extractFirstWord(name);
             // eslint-disable-next-line @typescript-eslint/no-explicit-any
-            if (PREPOSITIONS.includes(firstWord.toLowerCase())) {
+            const firstWordLower = firstWord.toLowerCase();
+            // Check for prepositions and common verbs first
+            if (PREPOSITIONS.includes(firstWordLower) || COMMON_VERBS.has(firstWordLower)) {
                 return true;
             }
-            const tags = getPossibleTags(toSentence(name));
-            const isVerb = tags.includes('Verb');
-            const isPreposition = tags.includes('Preposition');
-            const isConjunction = tags.includes('Conjunction');
-            return isVerb || isPreposition || isConjunction;
+            // Try both with and without "I" prefix to catch more verb forms
+            const withPrefixTags = getPossibleTags(toSentence(name));
+            const withoutPrefixTags = getPossibleTags(firstWord);
+            // Check if either form is recognized as a verb
+            const isVerb = withPrefixTags.includes('Verb') || withoutPrefixTags.includes('Verb');
+            const isPreposition = withPrefixTags.includes('Preposition');
+            const isConjunction = withPrefixTags.includes('Conjunction');
+            // For non-prepositions/conjunctions, require verb form
+            if (isPreposition || isConjunction) {
+                return true;
+            }
+            return isVerb;
         }
         function isJsxReturnFunction(node) {
             if (node.type !== utils_1.AST_NODE_TYPES.FunctionDeclaration &&
@@ -99,6 +125,12 @@ exports.enforceVerbNounNaming = (0, createRule_1.createRule)({
             MethodDefinition(node) {
                 if (node.key.type !== utils_1.AST_NODE_TYPES.Identifier)
                     return;
+                // Skip getters since they represent properties and should use noun phrases
+                if (node.kind === 'get')
+                    return;
+                // Skip constructors since they are special class methods
+                if (node.kind === 'constructor')
+                    return;
                 if (!isVerbPhrase(node.key.name)) {
                     context.report({
                         node: node.key,

package/lib/rules/no-async-array-filter.js

@@ -27,12 +27,12 @@ exports.noAsyncArrayFilter = (0, createRule_1.createRule)({
     meta: {
         type: 'problem',
         docs: {
-            description: 'Disallow async callbacks for Array.filter',
+            description: 'Disallow async callbacks in Array.filter() as they lead to incorrect filtering. Since async functions return Promises which are always truthy, the filter will keep all elements regardless of the async check\'s result. Use Promise.all() with map() first, then filter based on the resolved results.',
             recommended: 'error',
         },
         schema: [],
         messages: {
-            unexpected: 'Async array filter is dangerous as a Promise object will always be truthy. You should move the asynchronous logic elsewhere.',
+            unexpected: 'Async array filter is dangerous as a Promise object will always be truthy. Instead of `array.filter(async x => await someCheck(x))`, first resolve the promises with `Promise.all()` or move the async logic elsewhere: `const results = await Promise.all(array.map(x => someCheck(x))); array.filter((_, i) => results[i])`.',
         },
     },
     defaultOptions: [],

package/lib/rules/no-async-foreach.js

@@ -24,7 +24,7 @@ exports.noAsyncForEach = {
     meta: {
         type: 'problem',
         docs: {
-            description: 'Disallow Array.forEach with an async callback function',
+            description: 'Disallow Array.forEach with an async callback function as it does not wait for promises to resolve. This can lead to race conditions and unexpected behavior. Use a standard for...of loop for sequential execution or Promise.all with map for concurrent execution.',
             recommended: 'error',
         },
         messages: {

package/lib/rules/no-class-instance-destructuring.d.ts

@@ -0,0 +1 @@
+export declare const noClassInstanceDestructuring: import("@typescript-eslint/utils/dist/ts-eslint/Rule").RuleModule<"noClassInstanceDestructuring", [], import("@typescript-eslint/utils/dist/ts-eslint/Rule").RuleListener>;