@blumintinc/eslint-plugin-blumint 1.13.0 → 1.15.0

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

@@ -37,8 +37,12 @@ module.exports = (0, createRule_1.createRule)({
         fixable: 'code',
         schema: [],
         messages: {
-            callbackPropPrefix: 'Callback props (function type props) must be prefixed with "on" (e.g., onClick, onChange)',
-            callbackFunctionPrefix: 'Callback functions should not use "handle" prefix, use descriptive verb phrases instead',
+            callbackPropPrefix: 'Callback prop "{{propName}}" is a function but lacks the "on" prefix. ' +
+                'Consistent "on" prefixes signal event handlers to consumers and distinguish callbacks from data props. ' +
+                'Rename to "on{{eventName}}".',
+            callbackFunctionPrefix: 'Function "{{functionName}}" uses the "handle" prefix. ' +
+                'The "handle" prefix is redundant and less descriptive than action-oriented verb phrases. ' +
+                'Rename using a descriptive verb (e.g., click instead of handleClick).',
         },
     },
     defaultOptions: [],
@@ -91,6 +95,28 @@ module.exports = (0, createRule_1.createRule)({
             const type = checker.getTypeAtLocation(tsNode);
             return type.getCallSignatures().length > 0;
         }
+        function isRenderFunction(node) {
+            const tsNode = parserServices.esTreeNodeToTSNodeMap.get(node);
+            const type = checker.getTypeAtLocation(tsNode);
+            const signatures = type.getCallSignatures();
+            if (signatures.length === 0)
+                return false;
+            const isReactType = (t) => {
+                const typeStr = checker.typeToString(t);
+                return (typeStr.includes('JSX.Element') ||
+                    typeStr.includes('ReactElement') ||
+                    typeStr.includes('ReactNode'));
+            };
+            return signatures.some((signature) => {
+                const returnType = checker.getReturnTypeOfSignature(signature);
+                if (isReactType(returnType))
+                    return true;
+                if (returnType.isUnion()) {
+                    return returnType.types.some((t) => isReactType(t));
+                }
+                return false;
+            });
+        }
         return {
             // Check JSX attributes for callback props
             JSXAttribute(node) {
@@ -137,13 +163,19 @@ module.exports = (0, createRule_1.createRule)({
                     if (isFunctionType(node.value.expression) &&
                         propName &&
                         !propName.startsWith('on') &&
+                        !propName.startsWith('render') &&
+                        !isRenderFunction(node.value.expression) &&
                         !isReactComponentType(node.value.expression)) {
+                        const eventName = propName.charAt(0).toUpperCase() + propName.slice(1);
                         context.report({
                             node,
                             messageId: 'callbackPropPrefix',
+                            data: {
+                                propName,
+                                eventName,
+                            },
                             fix(fixer) {
                                 // Convert camelCase to PascalCase for the event name
-                                const eventName = propName.charAt(0).toUpperCase() + propName.slice(1);
                                 return fixer.replaceText(node.name, `on${eventName}`);
                             },
                         });
@@ -159,6 +191,7 @@ module.exports = (0, createRule_1.createRule)({
                         context.report({
                             node,
                             messageId: 'callbackFunctionPrefix',
+                            data: { functionName },
                         });
                         return;
                     }
@@ -169,6 +202,7 @@ module.exports = (0, createRule_1.createRule)({
                         context.report({
                             node,
                             messageId: 'callbackFunctionPrefix',
+                            data: { functionName },
                         });
                         return;
                     }
@@ -210,7 +244,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) {
@@ -220,6 +254,7 @@ module.exports = (0, createRule_1.createRule)({
                     context.report({
                         node,
                         messageId: 'callbackFunctionPrefix',
+                        data: { functionName },
                         fix(fixer) {
                             // Remove 'handle' prefix and convert first character to lowercase
                             const newName = functionName.slice(6).charAt(0).toLowerCase() +
@@ -248,6 +283,7 @@ module.exports = (0, createRule_1.createRule)({
                         context.report({
                             node: node.key,
                             messageId: 'callbackFunctionPrefix',
+                            data: { functionName: name },
                         });
                         return;
                     }
@@ -256,12 +292,14 @@ module.exports = (0, createRule_1.createRule)({
                         context.report({
                             node: node.key,
                             messageId: 'callbackFunctionPrefix',
+                            data: { functionName: name },
                         });
                         return;
                     }
                     context.report({
                         node: node.key,
                         messageId: 'callbackFunctionPrefix',
+                        data: { functionName: name },
                         fix(fixer) {
                             // Remove 'handle' prefix and convert first character to lowercase
                             const newName = name.slice(6).charAt(0).toLowerCase() + name.slice(7);
@@ -277,6 +315,7 @@ module.exports = (0, createRule_1.createRule)({
                     context.report({
                         node,
                         messageId: 'callbackFunctionPrefix',
+                        data: { functionName: node.parameter.name },
                     });
                 }
             },

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

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

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

@@ -4,81 +4,171 @@ 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' &&
+    if (callee.type === utils_1.AST_NODE_TYPES.MemberExpression) {
+        return (callee.object.type === utils_1.AST_NODE_TYPES.Identifier &&
             callee.object.name === 'https' &&
-            callee.property.type === 'Identifier' &&
+            callee.property.type === utils_1.AST_NODE_TYPES.Identifier &&
             callee.property.name === 'HttpsError');
     }
-    else if (callee.type === 'Identifier') {
+    else if (callee.type === utils_1.AST_NODE_TYPES.Identifier) {
         return callee.name === 'HttpsError';
     }
     return false;
 };
+const findPropertyByName = (properties, name) => properties.find((p) => p.type === utils_1.AST_NODE_TYPES.Property &&
+    !p.computed &&
+    ((p.key.type === utils_1.AST_NODE_TYPES.Identifier && p.key.name === name) ||
+        (p.key.type === utils_1.AST_NODE_TYPES.Literal && p.key.value === name)));
 exports.dynamicHttpsErrors = (0, createRule_1.createRule)({
     name: 'dynamic-https-errors',
     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. All HttpsError constructor calls must include a third argument for contextual details.',
+            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.',
-            missingThirdArgument: "HttpsError constructor calls must include a third argument for contextual details. The third argument should contain relevant context that aids in debugging without affecting the error's unique identifier.",
+            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.',
+            missingDetailsProperty: 'HttpsError calls must include a "details" property. The message is hashed into a stable identifier, so omitting details leaves errors hard to debug and encourages packing variables into the hashed message. Provide a details property with the request-specific context (object or string) to keep identifiers stable and diagnostics useful.',
+            missingDetailsDueToSpread: 'HttpsError calls must include a "details" property. This call uses an object spread, which prevents static verification that "details" is present. Ensure the spread object contains "details" or provide it explicitly to keep identifiers stable and diagnostics useful.',
+            unexpectedExtraArgumentForObjectCall: 'Object-based HttpsError calls must have exactly one argument containing code, message, and details properties. Remove extra arguments or use the positional signature (code, message, details).',
         },
     },
     defaultOptions: [],
     create(context) {
+        const unwrapTSAssertions = (node) => {
+            let inner = node;
+            while (inner.type === utils_1.AST_NODE_TYPES.TSAsExpression ||
+                inner.type === utils_1.AST_NODE_TYPES.TSSatisfiesExpression ||
+                inner.type === utils_1.AST_NODE_TYPES.TSNonNullExpression ||
+                inner.type === utils_1.AST_NODE_TYPES.TSTypeAssertion) {
+                inner = inner.expression;
+            }
+            return inner;
+        };
+        // 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) => {
+                const inner = unwrapTSAssertions(expr);
+                return (inner.type === utils_1.AST_NODE_TYPES.Literal &&
+                    typeof inner.value === 'string');
+            };
+            const isSafe = (expr) => {
+                if (expr.type === utils_1.AST_NODE_TYPES.PrivateIdentifier) {
+                    return false;
+                }
+                const inner = unwrapTSAssertions(expr);
+                if (inner.type === utils_1.AST_NODE_TYPES.BinaryExpression) {
+                    return !isDynamicBinaryExpression(inner);
+                }
+                return isStaticLiteral(inner);
+            };
+            return !(isSafe(expression.left) && isSafe(expression.right));
+        };
+        /**
+         * Determines if a node should be validated for staticness.
+         *
+         * Pragmatic Exception: Identifier, MemberExpression, and ChainExpression nodes
+         * (e.g., `props.message`, `props?.message`, `ERROR_MSG`) are excluded from
+         * staticness validation. While they can be dynamic and may affect message
+         * stability, they are permitted to support common React/props patterns and
+         * constants, preserving developer ergonomics as an intentional trade-off.
+         */
+        const shouldValidateForStaticness = (node) => {
+            return (node.type !== utils_1.AST_NODE_TYPES.Identifier &&
+                node.type !== utils_1.AST_NODE_TYPES.MemberExpression &&
+                node.type !== utils_1.AST_NODE_TYPES.ChainExpression &&
+                node.type !== utils_1.AST_NODE_TYPES.SpreadElement &&
+                // Explicitly exclude patterns and other non-Expression nodes that can appear in Property.value
+                node.type !== utils_1.AST_NODE_TYPES.ArrayPattern &&
+                node.type !== utils_1.AST_NODE_TYPES.AssignmentPattern &&
+                node.type !== utils_1.AST_NODE_TYPES.ObjectPattern &&
+                node.type !== utils_1.AST_NODE_TYPES.RestElement &&
+                node.type !== utils_1.AST_NODE_TYPES.TSEmptyBodyFunctionExpression);
+        };
+        /**
+         * Checks if the message node is static.
+         *
+         * A message is considered static if it's a Literal (string), a TemplateLiteral with no expressions,
+         * or a BinaryExpression (string concatenation with '+') where all parts are static.
+         *
+         * This function reports `dynamicHttpsErrors` for all other expression types (CallExpression,
+         * ConditionalExpression, etc.) that reach it, except for those explicitly excluded by
+         * `shouldValidateForStaticness`.
+         */
+        const checkMessageIsStatic = (messageNode) => {
+            const currentNode = unwrapTSAssertions(messageNode);
+            if (currentNode.type === utils_1.AST_NODE_TYPES.Literal) {
+                return;
+            }
+            if (currentNode.type === utils_1.AST_NODE_TYPES.TemplateLiteral &&
+                currentNode.expressions.length === 0) {
+                return;
+            }
+            if (currentNode.type === utils_1.AST_NODE_TYPES.BinaryExpression) {
+                if (isDynamicBinaryExpression(currentNode)) {
+                    context.report({
+                        node: messageNode,
+                        messageId: 'dynamicHttpsErrors',
+                    });
+                }
+                return;
+            }
+            // Catch-all for other dynamic forms (CallExpression, ConditionalExpression, etc.)
+            context.report({
+                node: messageNode,
+                messageId: 'dynamicHttpsErrors',
+            });
+        };
         const checkForHttpsError = (node) => {
             const callee = node.callee;
-            if (isHttpsErrorCall(callee)) {
-                // Check for missing third argument
-                if (node.arguments.length < 3) {
+            if (!isHttpsErrorCall(callee))
+                return;
+            // Signature 1: Object-based constructor (HttpsErrorProps)
+            if (node.arguments.length >= 1 &&
+                node.arguments[0].type === utils_1.AST_NODE_TYPES.ObjectExpression) {
+                if (node.arguments.length > 1) {
                     context.report({
                         node,
-                        messageId: 'missingThirdArgument',
+                        messageId: 'unexpectedExtraArgumentForObjectCall',
                     });
                     return;
                 }
-                // Check for dynamic content in second argument (existing functionality)
-                const secondArg = node.arguments[1];
-                if (!secondArg)
-                    return;
-                if (secondArg.type === utils_1.AST_NODE_TYPES.TemplateLiteral &&
-                    secondArg.expressions.length > 0) {
+                const props = node.arguments[0];
+                const messageProperty = findPropertyByName(props.properties, 'message');
+                const detailsProperty = findPropertyByName(props.properties, 'details');
+                if (!detailsProperty) {
+                    const hasSpread = props.properties.some((p) => p.type === utils_1.AST_NODE_TYPES.SpreadElement);
                     context.report({
-                        node: secondArg,
-                        messageId: 'dynamicHttpsErrors',
+                        node,
+                        messageId: hasSpread
+                            ? 'missingDetailsDueToSpread'
+                            : 'missingDetailsProperty',
                     });
-                    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',
-                    });
+                if (messageProperty &&
+                    shouldValidateForStaticness(messageProperty.value)) {
+                    checkMessageIsStatic(messageProperty.value);
                 }
+                return;
+            }
+            // Signature 2: Positional arguments (code, message, details)
+            // Check for missing third argument
+            if (node.arguments.length < 3) {
+                context.report({
+                    node,
+                    messageId: 'missingThirdArgument',
+                });
+            }
+            // Check for dynamic content in second argument
+            const secondArg = node.arguments[1];
+            if (secondArg && shouldValidateForStaticness(secondArg)) {
+                checkMessageIsStatic(secondArg);
             }
         };
         return {

package/lib/rules/enforce-assert-safe-object-key.js

@@ -34,7 +34,7 @@ exports.enforceAssertSafeObjectKey = (0, createRule_1.createRule)({
          * 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 '${importPath}';\n`;
             if (firstImport) {
@@ -83,7 +83,7 @@ exports.enforceAssertSafeObjectKey = (0, createRule_1.createRule)({
                         key.callee.type === utils_1.AST_NODE_TYPES.Identifier &&
                         key.callee.name === 'String') {
                         const arg = key.arguments[0];
-                        const argText = context.getSourceCode().getText(arg);
+                        const argText = context.sourceCode.getText(arg);
                         reportUseAssertSafe(key, argText);
                     }
                     // Check for template literals like `${id}`
@@ -93,7 +93,7 @@ exports.enforceAssertSafeObjectKey = (0, createRule_1.createRule)({
                         key.quasis[0].value.raw === '' &&
                         key.quasis[1].value.raw === '') {
                         const expr = key.expressions[0];
-                        const exprText = context.getSourceCode().getText(expr);
+                        const exprText = context.sourceCode.getText(expr);
                         reportUseAssertSafe(key, exprText);
                     }
                 }
@@ -107,7 +107,7 @@ exports.enforceAssertSafeObjectKey = (0, createRule_1.createRule)({
                         left.callee.type === utils_1.AST_NODE_TYPES.Identifier &&
                         left.callee.name === 'String') {
                         const arg = left.arguments[0];
-                        const argText = context.getSourceCode().getText(arg);
+                        const argText = context.sourceCode.getText(arg);
                         reportUseAssertSafe(left, argText);
                     }
                     // Check for template literals like `${id}`
@@ -117,7 +117,7 @@ exports.enforceAssertSafeObjectKey = (0, createRule_1.createRule)({
                         left.quasis[0].value.raw === '' &&
                         left.quasis[1].value.raw === '') {
                         const expr = left.expressions[0];
-                        const exprText = context.getSourceCode().getText(expr);
+                        const exprText = context.sourceCode.getText(expr);
                         reportUseAssertSafe(left, exprText);
                     }
                 }
@@ -158,7 +158,7 @@ exports.enforceAssertSafeObjectKey = (0, createRule_1.createRule)({
                         property.callee.type === utils_1.AST_NODE_TYPES.Identifier &&
                         property.callee.name === 'String') {
                         const arg = property.arguments[0];
-                        const argText = context.getSourceCode().getText(arg);
+                        const argText = context.sourceCode.getText(arg);
                         reportUseAssertSafe(property, argText);
                         return;
                     }
@@ -179,7 +179,7 @@ exports.enforceAssertSafeObjectKey = (0, createRule_1.createRule)({
                             return;
                         }
                         const expr = property.expressions[0];
-                        const exprText = context.getSourceCode().getText(expr);
+                        const exprText = context.sourceCode.getText(expr);
                         reportUseAssertSafe(property, exprText);
                         return;
                     }
@@ -193,7 +193,7 @@ exports.enforceAssertSafeObjectKey = (0, createRule_1.createRule)({
                         if (isLikelyArray) {
                             return;
                         }
-                        const propText = context.getSourceCode().getText(property);
+                        const propText = context.sourceCode.getText(property);
                         reportUseAssertSafe(property, propText);
                         return;
                     }
@@ -203,7 +203,7 @@ exports.enforceAssertSafeObjectKey = (0, createRule_1.createRule)({
                         if (isLikelyArray) {
                             return;
                         }
-                        const propText = context.getSourceCode().getText(property);
+                        const propText = context.sourceCode.getText(property);
                         reportUseAssertSafe(property, propText);
                         return;
                     }
@@ -215,7 +215,7 @@ exports.enforceAssertSafeObjectKey = (0, createRule_1.createRule)({
                         if (isLikelyArray) {
                             return;
                         }
-                        const propText = context.getSourceCode().getText(property);
+                        const propText = context.sourceCode.getText(property);
                         reportUseAssertSafe(property, propText);
                         return;
                     }
@@ -228,7 +228,7 @@ exports.enforceAssertSafeObjectKey = (0, createRule_1.createRule)({
                         if (isLikelyArray) {
                             return;
                         }
-                        const propText = context.getSourceCode().getText(property);
+                        const propText = context.sourceCode.getText(property);
                         reportUseAssertSafe(property, propText);
                         return;
                     }