@blumintinc/eslint-plugin-blumint 1.12.6 → 1.14.0

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

@@ -12,6 +12,7 @@ exports.ARRAY_METHODS = [
 ];
 exports.arrayMethodsThisContext = (0, createRule_1.createRule)({
     create(context) {
+        const sourceCode = context.sourceCode;
         return {
             CallExpression(node) {
                 // Array method called with a class method reference
@@ -21,9 +22,23 @@ exports.arrayMethodsThisContext = (0, createRule_1.createRule)({
                     node.arguments.length > 0 &&
                     node.arguments[0].type === 'MemberExpression' &&
                     node.arguments[0].object.type === 'ThisExpression') {
+                    const methodProperty = node.arguments[0].property;
+                    const methodAccessor = node.arguments[0].computed
+                        ? `[${sourceCode.getText(methodProperty)}]`
+                        : methodProperty.type === 'Identifier'
+                            ? `.${methodProperty.name}`
+                            : methodProperty.type === 'PrivateIdentifier'
+                                ? `.#${methodProperty.name}`
+                                : `.${sourceCode.getText(methodProperty)}`;
+                    const methodReference = `this${methodAccessor}`;
                     context.report({
                         node: node.arguments[0],
                         messageId: 'unexpected',
+                        data: {
+                            arrayMethod: node.callee.property.name,
+                            methodAccessor,
+                            methodReference,
+                        },
                     });
                 }
                 // Function expression bound to `this` in array method
@@ -41,6 +56,9 @@ exports.arrayMethodsThisContext = (0, createRule_1.createRule)({
                     context.report({
                         node: node.arguments[0],
                         messageId: 'preferArrow',
+                        data: {
+                            arrayMethod: node.callee.property.name,
+                        },
                     });
                 }
             },
@@ -55,8 +73,8 @@ exports.arrayMethodsThisContext = (0, createRule_1.createRule)({
         },
         schema: [],
         messages: {
-            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) => {...})`.',
+            unexpected: 'Array method "{{arrayMethod}}" receives the class method reference {{methodReference}}, which strips its "this" binding when the callback runs. Use an arrow callback so the class instance remains available, e.g. {{arrayMethod}}((item) => this{{methodAccessor}}(item)).',
+            preferArrow: 'Array method "{{arrayMethod}}" binds a callback with ".bind(this)", which allocates a new function and hides that the code depends on the class instance. Prefer an arrow callback that captures "this" without rebinding, e.g. {{arrayMethod}}((item) => this.handleItem(item)).',
         },
     },
     defaultOptions: [],

package/lib/rules/avoid-utils-directory.js

@@ -1,6 +1,10 @@
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.avoidUtilsDirectory = void 0;
+const path_1 = __importDefault(require("path"));
 const createRule_1 = require("../utils/createRule");
 exports.avoidUtilsDirectory = (0, createRule_1.createRule)({
     name: 'avoid-utils-directory',
@@ -10,10 +14,9 @@ exports.avoidUtilsDirectory = (0, createRule_1.createRule)({
             description: 'Enforce using util/ instead of utils/ directory',
             recommended: 'error',
         },
-        fixable: 'code',
         schema: [],
         messages: {
-            avoidUtils: 'Use "util/" directory instead of "utils/"',
+            avoidUtils: 'Path "{{path}}" lives under a "utils/" directory. Generic "utils" folders become grab bags where unrelated helpers accumulate, which makes imports unpredictable and hides ownership. Move this file into a focused "util/" folder (e.g., "util/date" or "util/string") so callers know where to find it and understand its responsibility.',
         },
     },
     defaultOptions: [],
@@ -21,6 +24,9 @@ exports.avoidUtilsDirectory = (0, createRule_1.createRule)({
         return {
             Program(node) {
                 const filename = context.getFilename();
+                const relativePath = path_1.default.isAbsolute(filename)
+                    ? path_1.default.relative(process.cwd(), filename) || filename
+                    : filename;
                 // Skip files in node_modules
                 if (filename.includes('node_modules')) {
                     return;
@@ -31,6 +37,9 @@ exports.avoidUtilsDirectory = (0, createRule_1.createRule)({
                     context.report({
                         node,
                         messageId: 'avoidUtils',
+                        data: {
+                            path: relativePath,
+                        },
                         fix() {
                             // We can't provide an auto-fix since directory renaming is beyond ESLint's scope
                             return null;

package/lib/rules/class-methods-read-top-to-bottom.js

@@ -15,23 +15,31 @@ exports.classMethodsReadTopToBottom = (0, createRule_1.createRule)({
     meta: {
         type: 'suggestion',
         docs: {
-            description: 'Ensures classes read linearly from top to bottom.',
+            description: 'Enforces a top-to-bottom class layout so callers lead into the helpers they rely on.',
             recommended: 'warn',
         },
         schema: [],
         messages: {
-            classMethodsReadTopToBottom: 'Methods should be ordered for top-down readability.',
+            classMethodsReadTopToBottom: [
+                "What's wrong: In {{className}}, {{actualMember}} appears before {{expectedMember}}.",
+                'Why it matters: Top-down flow enables local reasoning: you can verify each caller without scrolling back. Upward jumps make code reviews harder (must verify call chains in reverse), obscure which fields a helper assumes are initialized, and increase the risk of calling helpers before state is ready (leading to null reference errors or accessing uninitialized fields).',
+                'How to fix: Move {{expectedMember}} above {{actualMember}} so the class reads top-to-bottom (fields to constructor to callers to helpers).',
+            ].join('\n'),
         },
         fixable: 'code', // To allow ESLint to autofix issues.
     },
     defaultOptions: [],
     create(context) {
-        let className;
+        const classNames = new WeakMap();
         return {
             ClassDeclaration(node) {
-                className = node.id?.name || '';
+                classNames.set(node.body, node.id?.name || '');
+            },
+            ClassExpression(node) {
+                classNames.set(node.body, node.id?.name || '');
             },
             'ClassBody:exit'(node) {
+                const className = classNames.get(node) || '';
                 const graphBuilder = new ClassGraphBuilder_1.ClassGraphBuilder(className, node);
                 const sortedOrder = graphBuilder.memberNamesSorted;
                 const actualOrder = node.body
@@ -51,7 +59,13 @@ exports.classMethodsReadTopToBottom = (0, createRule_1.createRule)({
                     return; // Skip if there are actual duplicates
                 }
                 for (let i = 0; i < actualOrder.length; i++) {
-                    if (actualOrder[i] !== sortedOrder[i]) {
+                    const actualMember = actualOrder[i];
+                    const expectedMember = sortedOrder[i];
+                    if (!actualMember || !expectedMember) {
+                        throw new Error(`class-methods-read-top-to-bottom invariant violated while comparing members in ${className || 'an unnamed class'} at position ${i}: actualMember=${String(actualMember)}, expectedMember=${String(expectedMember)}, actualOrder.length=${actualOrder.length}, sortedOrder.length=${sortedOrder.length}`);
+                    }
+                    if (actualMember !== expectedMember) {
+                        const classNameReport = className || 'this class';
                         const sourceCode = context.getSourceCode();
                         const newClassBody = sortedOrder
                             .map((n) => {
@@ -75,6 +89,11 @@ exports.classMethodsReadTopToBottom = (0, createRule_1.createRule)({
                         return context.report({
                             node,
                             messageId: 'classMethodsReadTopToBottom',
+                            data: {
+                                className: classNameReport,
+                                actualMember,
+                                expectedMember,
+                            },
                             fix(fixer) {
                                 return fixer.replaceTextRange([node.range[0] + 1, node.range[1] - 1], // Exclude the curly braces
                                 newClassBody);

package/lib/rules/consistent-callback-naming.js

@@ -210,7 +210,7 @@ module.exports = (0, createRule_1.createRule)({
                         }
                     }
                     // Get references from global scope
-                    const sourceCode = context.getSourceCode();
+                    const sourceCode = context.sourceCode;
                     if (sourceCode.scopeManager?.globalScope) {
                         const globalVar = sourceCode.scopeManager.globalScope.variables.find((v) => v.name === functionName);
                         if (globalVar) {

package/lib/rules/dynamic-https-errors.d.ts

@@ -1,2 +1,4 @@
 import { TSESLint } from '@typescript-eslint/utils';
-export declare const dynamicHttpsErrors: TSESLint.RuleModule<'dynamicHttpsErrors', never[]>;
+type MessageIds = 'dynamicHttpsErrors' | 'missingThirdArgument';
+export declare const dynamicHttpsErrors: TSESLint.RuleModule<MessageIds, never[]>;
+export {};

package/lib/rules/dynamic-https-errors.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.dynamicHttpsErrors = void 0;
 const createRule_1 = require("../utils/createRule");
+const utils_1 = require("@typescript-eslint/utils");
 const isHttpsErrorCall = (callee) => {
     if (callee.type === 'MemberExpression') {
         return (callee.object.type === 'Identifier' &&
@@ -19,12 +20,13 @@ exports.dynamicHttpsErrors = (0, createRule_1.createRule)({
     meta: {
         type: 'suggestion',
         docs: {
-            description: 'Dynamic error details should only be in the third argument of the HttpsError constructor. The second argument is hashed to produce a unique id.',
+            description: 'Keep HttpsError messages static and move request-specific details to the third argument so error identifiers remain stable and debugging context is preserved.',
             recommended: 'error',
         },
         schema: [],
         messages: {
-            dynamicHttpsErrors: 'Found dynamic error details in the second argument of the HttpsError constructor - the "message" field. This field is hashed to produce a unique id for error monitoring. Move any dynamic details to the third argument - the "details" field - to preserve the unique id and to monitor the error correctly.',
+            dynamicHttpsErrors: 'The HttpsError message (second argument) must stay static. Template expressions here change the hashed message and explode the number of error ids for the same failure. Keep this argument constant and move interpolated values into the third "details" argument so monitoring groups the error while still capturing request context.',
+            missingThirdArgument: 'HttpsError calls must include a third "details" argument. The message (second argument) is hashed into a stable identifier, so omitting details leaves errors hard to debug and encourages packing variables into the hashed message. Provide a third argument with the request-specific context (object or string) to keep identifiers stable and diagnostics useful.',
         },
     },
     defaultOptions: [],
@@ -32,23 +34,58 @@ exports.dynamicHttpsErrors = (0, createRule_1.createRule)({
         const checkForHttpsError = (node) => {
             const callee = node.callee;
             if (isHttpsErrorCall(callee)) {
+                // Check for missing third argument
+                if (node.arguments.length < 3) {
+                    context.report({
+                        node,
+                        messageId: 'missingThirdArgument',
+                    });
+                }
+                // Check for dynamic content in second argument (existing functionality)
                 const secondArg = node.arguments[1];
-                if (secondArg && secondArg.type === 'TemplateLiteral') {
-                    if (secondArg.expressions.length > 0) {
-                        context.report({
-                            node: secondArg,
-                            messageId: 'dynamicHttpsErrors',
-                        });
-                    }
+                if (!secondArg)
+                    return;
+                if (secondArg.type === utils_1.AST_NODE_TYPES.TemplateLiteral &&
+                    secondArg.expressions.length > 0) {
+                    context.report({
+                        node: secondArg,
+                        messageId: 'dynamicHttpsErrors',
+                    });
+                    return;
+                }
+                // Only string concatenation with "+" can be static; all other operators
+                // are treated as dynamic to avoid hashing non-literal message content.
+                const isDynamicBinaryExpression = (expression) => {
+                    if (expression.operator !== '+')
+                        return true;
+                    const isStaticLiteral = (expr) => expr.type === utils_1.AST_NODE_TYPES.Literal &&
+                        typeof expr.value === 'string';
+                    const isSafe = (expr) => {
+                        if (expr.type === utils_1.AST_NODE_TYPES.PrivateIdentifier) {
+                            return false;
+                        }
+                        if (expr.type === utils_1.AST_NODE_TYPES.BinaryExpression) {
+                            return !isDynamicBinaryExpression(expr);
+                        }
+                        return isStaticLiteral(expr);
+                    };
+                    return !(isSafe(expression.left) && isSafe(expression.right));
+                };
+                if (secondArg.type === utils_1.AST_NODE_TYPES.BinaryExpression &&
+                    isDynamicBinaryExpression(secondArg)) {
+                    context.report({
+                        node: secondArg,
+                        messageId: 'dynamicHttpsErrors',
+                    });
                 }
             }
         };
         return {
             NewExpression(node) {
-                return checkForHttpsError(node);
+                checkForHttpsError(node);
             },
             CallExpression(node) {
-                return checkForHttpsError(node);
+                checkForHttpsError(node);
             },
         };
     },

package/lib/rules/enforce-assert-safe-object-key.d.ts

@@ -0,0 +1,8 @@
+import { TSESLint } from '@typescript-eslint/utils';
+type Options = [
+    {
+        readonly assertSafeImportPath?: string;
+    }
+];
+export declare const enforceAssertSafeObjectKey: TSESLint.RuleModule<"useAssertSafe", Options, TSESLint.RuleListener>;
+export {};

package/lib/rules/{enforce-assertSafe-object-key.js → enforce-assert-safe-object-key.js}

@@ -3,8 +3,9 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.enforceAssertSafeObjectKey = void 0;
 const utils_1 = require("@typescript-eslint/utils");
 const createRule_1 = require("../utils/createRule");
+const DEFAULT_IMPORT_PATH = 'functions/src/util/assertSafe';
 exports.enforceAssertSafeObjectKey = (0, createRule_1.createRule)({
-    name: 'enforce-assertSafe-object-key',
+    name: 'enforce-assert-safe-object-key',
     meta: {
         type: 'problem',
         docs: {
@@ -12,21 +13,30 @@ exports.enforceAssertSafeObjectKey = (0, createRule_1.createRule)({
             recommended: 'error',
         },
         fixable: 'code',
-        schema: [],
+        schema: [
+            {
+                type: 'object',
+                properties: {
+                    assertSafeImportPath: { type: 'string' },
+                },
+                additionalProperties: false,
+            },
+        ],
         messages: {
-            useAssertSafe: 'Use assertSafe() for object key access to ensure safe property access. Replace `obj[String(id)]` or `obj[`${id}`]` with `obj[assertSafe(id)]`.',
+            useAssertSafe: 'Dynamic object key "{{key}}" is used without assertSafe() validation. Unvalidated keys can resolve to unexpected properties (including prototype fields) and make lookups fragile or unsafe. Wrap the key with assertSafe({{key}}) before accessing the object.',
         },
     },
-    defaultOptions: [],
-    create(context) {
+    defaultOptions: [{}],
+    create(context, [options]) {
+        const importPath = options?.assertSafeImportPath || DEFAULT_IMPORT_PATH;
         let hasAssertSafeImport = false;
         /**
          * Helper function to add assertSafe import if needed
          */
         const addAssertSafeImport = (fixer) => {
-            const program = context.getSourceCode().ast;
+            const program = context.sourceCode.ast;
             const firstImport = program.body.find((node) => node.type === utils_1.AST_NODE_TYPES.ImportDeclaration);
-            const importStatement = "import { assertSafe } from 'functions/src/util/assertSafe';\n";
+            const importStatement = `import { assertSafe } from '${importPath}';\n`;
             if (firstImport) {
                 return fixer.insertTextBefore(firstImport, importStatement);
             }
@@ -48,6 +58,14 @@ exports.enforceAssertSafeObjectKey = (0, createRule_1.createRule)({
             fixes.push(fixer.replaceText(node, `assertSafe(${argText})`));
             return fixes;
         };
+        const reportUseAssertSafe = (node, expressionText) => context.report({
+            node,
+            messageId: 'useAssertSafe',
+            data: { key: expressionText },
+            fix(fixer) {
+                return createFixes(fixer, node, expressionText);
+            },
+        });
         return {
             ImportDeclaration(node) {
                 // Check if assertSafe is already imported
@@ -64,15 +82,9 @@ exports.enforceAssertSafeObjectKey = (0, createRule_1.createRule)({
                     if (key.type === utils_1.AST_NODE_TYPES.CallExpression &&
                         key.callee.type === utils_1.AST_NODE_TYPES.Identifier &&
                         key.callee.name === 'String') {
-                        context.report({
-                            node: key,
-                            messageId: 'useAssertSafe',
-                            fix(fixer) {
-                                const arg = key.arguments[0];
-                                const argText = context.getSourceCode().getText(arg);
-                                return createFixes(fixer, key, argText);
-                            },
-                        });
+                        const arg = key.arguments[0];
+                        const argText = context.sourceCode.getText(arg);
+                        reportUseAssertSafe(key, argText);
                     }
                     // Check for template literals like `${id}`
                     if (key.type === utils_1.AST_NODE_TYPES.TemplateLiteral &&
@@ -80,15 +92,9 @@ exports.enforceAssertSafeObjectKey = (0, createRule_1.createRule)({
                         key.quasis.length === 2 &&
                         key.quasis[0].value.raw === '' &&
                         key.quasis[1].value.raw === '') {
-                        context.report({
-                            node: key,
-                            messageId: 'useAssertSafe',
-                            fix(fixer) {
-                                const expr = key.expressions[0];
-                                const exprText = context.getSourceCode().getText(expr);
-                                return createFixes(fixer, key, exprText);
-                            },
-                        });
+                        const expr = key.expressions[0];
+                        const exprText = context.sourceCode.getText(expr);
+                        reportUseAssertSafe(key, exprText);
                     }
                 }
             },
@@ -100,15 +106,9 @@ exports.enforceAssertSafeObjectKey = (0, createRule_1.createRule)({
                     if (left.type === utils_1.AST_NODE_TYPES.CallExpression &&
                         left.callee.type === utils_1.AST_NODE_TYPES.Identifier &&
                         left.callee.name === 'String') {
-                        context.report({
-                            node: left,
-                            messageId: 'useAssertSafe',
-                            fix(fixer) {
-                                const arg = left.arguments[0];
-                                const argText = context.getSourceCode().getText(arg);
-                                return createFixes(fixer, left, argText);
-                            },
-                        });
+                        const arg = left.arguments[0];
+                        const argText = context.sourceCode.getText(arg);
+                        reportUseAssertSafe(left, argText);
                     }
                     // Check for template literals like `${id}`
                     if (left.type === utils_1.AST_NODE_TYPES.TemplateLiteral &&
@@ -116,15 +116,9 @@ exports.enforceAssertSafeObjectKey = (0, createRule_1.createRule)({
                         left.quasis.length === 2 &&
                         left.quasis[0].value.raw === '' &&
                         left.quasis[1].value.raw === '') {
-                        context.report({
-                            node: left,
-                            messageId: 'useAssertSafe',
-                            fix(fixer) {
-                                const expr = left.expressions[0];
-                                const exprText = context.getSourceCode().getText(expr);
-                                return createFixes(fixer, left, exprText);
-                            },
-                        });
+                        const expr = left.expressions[0];
+                        const exprText = context.sourceCode.getText(expr);
+                        reportUseAssertSafe(left, exprText);
                     }
                 }
             },
@@ -163,15 +157,9 @@ exports.enforceAssertSafeObjectKey = (0, createRule_1.createRule)({
                     if (property.type === utils_1.AST_NODE_TYPES.CallExpression &&
                         property.callee.type === utils_1.AST_NODE_TYPES.Identifier &&
                         property.callee.name === 'String') {
-                        context.report({
-                            node: property,
-                            messageId: 'useAssertSafe',
-                            fix(fixer) {
-                                const arg = property.arguments[0];
-                                const argText = context.getSourceCode().getText(arg);
-                                return createFixes(fixer, property, argText);
-                            },
-                        });
+                        const arg = property.arguments[0];
+                        const argText = context.sourceCode.getText(arg);
+                        reportUseAssertSafe(property, argText);
                         return;
                     }
                     // Check for template literals
@@ -190,16 +178,9 @@ exports.enforceAssertSafeObjectKey = (0, createRule_1.createRule)({
                             // Complex template literals with additional text are fine
                             return;
                         }
-                        context.report({
-                            node: property,
-                            messageId: 'useAssertSafe',
-                            fix(fixer) {
-                                // Extract the expression from the template literal
-                                const expr = property.expressions[0];
-                                const exprText = context.getSourceCode().getText(expr);
-                                return createFixes(fixer, property, exprText);
-                            },
-                        });
+                        const expr = property.expressions[0];
+                        const exprText = context.sourceCode.getText(expr);
+                        reportUseAssertSafe(property, exprText);
                         return;
                     }
                     // Check for direct variable usage (identifiers)
@@ -212,15 +193,8 @@ exports.enforceAssertSafeObjectKey = (0, createRule_1.createRule)({
                         if (isLikelyArray) {
                             return;
                         }
-                        context.report({
-                            node: property,
-                            messageId: 'useAssertSafe',
-                            fix(fixer) {
-                                // For direct variable use, just use the variable name
-                                const propText = context.getSourceCode().getText(property);
-                                return createFixes(fixer, property, propText);
-                            },
-                        });
+                        const propText = context.sourceCode.getText(property);
+                        reportUseAssertSafe(property, propText);
                         return;
                     }
                     // Check for binary expressions (like index + 1)
@@ -229,14 +203,8 @@ exports.enforceAssertSafeObjectKey = (0, createRule_1.createRule)({
                         if (isLikelyArray) {
                             return;
                         }
-                        context.report({
-                            node: property,
-                            messageId: 'useAssertSafe',
-                            fix(fixer) {
-                                const propText = context.getSourceCode().getText(property);
-                                return createFixes(fixer, property, propText);
-                            },
-                        });
+                        const propText = context.sourceCode.getText(property);
+                        reportUseAssertSafe(property, propText);
                         return;
                     }
                     // Check for boolean expressions and other literals
@@ -247,14 +215,8 @@ exports.enforceAssertSafeObjectKey = (0, createRule_1.createRule)({
                         if (isLikelyArray) {
                             return;
                         }
-                        context.report({
-                            node: property,
-                            messageId: 'useAssertSafe',
-                            fix(fixer) {
-                                const propText = context.getSourceCode().getText(property);
-                                return createFixes(fixer, property, propText);
-                            },
-                        });
+                        const propText = context.sourceCode.getText(property);
+                        reportUseAssertSafe(property, propText);
                         return;
                     }
                     // Check for function calls (anything that isn't handled above)
@@ -266,14 +228,8 @@ exports.enforceAssertSafeObjectKey = (0, createRule_1.createRule)({
                         if (isLikelyArray) {
                             return;
                         }
-                        context.report({
-                            node: property,
-                            messageId: 'useAssertSafe',
-                            fix(fixer) {
-                                const propText = context.getSourceCode().getText(property);
-                                return createFixes(fixer, property, propText);
-                            },
-                        });
+                        const propText = context.sourceCode.getText(property);
+                        reportUseAssertSafe(property, propText);
                         return;
                     }
                 }
@@ -281,4 +237,4 @@ exports.enforceAssertSafeObjectKey = (0, createRule_1.createRule)({
         };
     },
 });
-//# sourceMappingURL=enforce-assertSafe-object-key.js.map
+//# sourceMappingURL=enforce-assert-safe-object-key.js.map

package/lib/rules/enforce-assert-throws.d.ts

@@ -1 +1,3 @@
-export declare const enforceAssertThrows: import("@typescript-eslint/utils/dist/ts-eslint/Rule").RuleModule<"assertShouldThrow", [], import("@typescript-eslint/utils/dist/ts-eslint/Rule").RuleListener>;
+type MessageIds = 'assertShouldThrow' | 'shouldBeAssertPrefixed';
+export declare const enforceAssertThrows: import("@typescript-eslint/utils/dist/ts-eslint/Rule").RuleModule<MessageIds, [], import("@typescript-eslint/utils/dist/ts-eslint/Rule").RuleListener>;
+export {};