@blumintinc/eslint-plugin-blumint 1.13.0 → 1.14.0

package/lib/rules/react-memoize-literals.js

@@ -0,0 +1,495 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.reactMemoizeLiterals = void 0;
+const utils_1 = require("@typescript-eslint/utils");
+const createRule_1 = require("../utils/createRule");
+const LITERAL_DESCRIPTOR_BY_TYPE = {
+    [utils_1.AST_NODE_TYPES.ObjectExpression]: {
+        literalType: 'object literal',
+        memoHook: 'useMemo',
+    },
+    [utils_1.AST_NODE_TYPES.ArrayExpression]: {
+        literalType: 'array literal',
+        memoHook: 'useMemo',
+    },
+    [utils_1.AST_NODE_TYPES.ArrowFunctionExpression]: {
+        literalType: 'inline function',
+        memoHook: 'useCallback',
+    },
+    [utils_1.AST_NODE_TYPES.FunctionExpression]: {
+        literalType: 'inline function',
+        memoHook: 'useCallback',
+    },
+    [utils_1.AST_NODE_TYPES.FunctionDeclaration]: {
+        literalType: 'inline function',
+        memoHook: 'useCallback',
+    },
+};
+const SAFE_HOOK_ARGUMENTS = new Set([
+    'useMemo',
+    'useCallback',
+    'useEffect',
+    'useLayoutEffect',
+    'useInsertionEffect',
+    'useImperativeHandle',
+    'useState',
+    'useReducer',
+    'useRef',
+    'useSyncExternalStore',
+    'useDeferredValue',
+    'useTransition',
+    'useId',
+]);
+const MEMOIZATION_DEPS_TODO_PLACEHOLDER = '__TODO_MEMOIZATION_DEPENDENCIES__';
+const TODO_DEPS_COMMENT = `/* ${MEMOIZATION_DEPS_TODO_PLACEHOLDER} */`;
+const PARENTHESIZED_EXPRESSION_TYPE = utils_1.AST_NODE_TYPES.ParenthesizedExpression ??
+    'ParenthesizedExpression';
+/**
+ * Detects React hook-style identifiers prefixed with "use".
+ * @param name Candidate identifier name.
+ * @returns True when the name follows the hook naming convention.
+ */
+function isHookName(name) {
+    return !!name && /^use[A-Z]/.test(name);
+}
+/**
+ * Detects PascalCase identifiers commonly used for React components.
+ * @param name Candidate identifier name.
+ * @returns True when the name begins with an uppercase character.
+ */
+function isComponentName(name) {
+    return !!name && /^[A-Z]/.test(name);
+}
+/**
+ * Type guard for parenthesized expressions to unwrap safely.
+ * @param node Node to evaluate.
+ * @returns True when the node is a parenthesized expression wrapper.
+ */
+function isParenthesizedExpression(node) {
+    return node.type === PARENTHESIZED_EXPRESSION_TYPE;
+}
+/**
+ * Extracts an identifier name from variable, assignment, or property nodes.
+ * @param node AST node that may carry an identifier.
+ * @returns Identifier name when present, otherwise null.
+ */
+function getNameFromNode(node) {
+    if (!node)
+        return null;
+    if (node.type === utils_1.AST_NODE_TYPES.VariableDeclarator &&
+        node.id.type === utils_1.AST_NODE_TYPES.Identifier) {
+        return node.id.name;
+    }
+    if (node.type === utils_1.AST_NODE_TYPES.AssignmentExpression &&
+        node.left.type === utils_1.AST_NODE_TYPES.Identifier) {
+        return node.left.name;
+    }
+    if (node.type === utils_1.AST_NODE_TYPES.Property &&
+        node.key.type === utils_1.AST_NODE_TYPES.Identifier) {
+        return node.key.name;
+    }
+    return null;
+}
+/**
+ * Determines whether a node should be traversed through when resolving names.
+ * @param node Node to evaluate for transparency.
+ * @returns True when the node does not introduce a binding boundary.
+ */
+function isTransparentNode(node) {
+    return (node.type === utils_1.AST_NODE_TYPES.CallExpression ||
+        node.type === utils_1.AST_NODE_TYPES.MemberExpression ||
+        isExpressionWrapper(node));
+}
+/**
+ * Walks ancestors through transparent nodes to find the nearest identifier name.
+ * @param startNode Node where the search begins.
+ * @returns Resolved identifier name or null if none is located.
+ */
+function findNameInAncestors(startNode) {
+    let current = startNode;
+    while (current) {
+        const name = getNameFromNode(current);
+        if (name) {
+            return name;
+        }
+        if (!isTransparentNode(current)) {
+            break;
+        }
+        current = current.parent;
+    }
+    return null;
+}
+/**
+ * Resolves a function's display name from its declaration or surrounding
+ * assignment/property wrappers so HOC-wrapped and asserted components still map
+ * to their intended identifiers.
+ */
+function getFunctionName(fn) {
+    if (fn.type === utils_1.AST_NODE_TYPES.FunctionDeclaration) {
+        return fn.id?.name ?? null;
+    }
+    if (fn.type === utils_1.AST_NODE_TYPES.FunctionExpression && fn.id?.name) {
+        return fn.id.name;
+    }
+    const parent = fn.parent;
+    if (!parent) {
+        return null;
+    }
+    const immediateName = getNameFromNode(parent);
+    if (immediateName) {
+        return immediateName;
+    }
+    return findNameInAncestors(parent);
+}
+/**
+ * Checks whether a function should be treated as a React component or hook
+ * based on naming conventions. Enables the rule to limit reports to user-facing
+ * components and hooks rather than arbitrary functions.
+ */
+function isComponentOrHookFunction(fn) {
+    const name = getFunctionName(fn);
+    return isComponentName(name) || isHookName(name);
+}
+/**
+ * Checks whether a function node represents a hook by name.
+ * @param fn Function node to inspect.
+ * @returns True when the function follows hook naming.
+ */
+function isHookFunction(fn) {
+    return isHookName(getFunctionName(fn));
+}
+/**
+ * Narrows nodes to the supported function-like shapes.
+ * @param node Node to test.
+ * @returns True when the node is any function declaration or expression.
+ */
+function isFunctionNode(node) {
+    return (node.type === utils_1.AST_NODE_TYPES.FunctionDeclaration ||
+        node.type === utils_1.AST_NODE_TYPES.FunctionExpression ||
+        node.type === utils_1.AST_NODE_TYPES.ArrowFunctionExpression);
+}
+/**
+ * Extracts a hook name from simple identifier or member-expression callees.
+ * @param callee Callee expression from a call.
+ * @returns Hook name when available, otherwise null.
+ */
+function getHookNameFromCallee(callee) {
+    const resolvedCallee = unwrapNestedExpressions(callee);
+    if (resolvedCallee.type === utils_1.AST_NODE_TYPES.Identifier) {
+        return resolvedCallee.name;
+    }
+    if (resolvedCallee.type === utils_1.AST_NODE_TYPES.MemberExpression &&
+        !resolvedCallee.computed &&
+        resolvedCallee.property.type ===
+            utils_1.AST_NODE_TYPES.Identifier) {
+        const property = resolvedCallee.property;
+        return property.name;
+    }
+    return null;
+}
+/**
+ * Detects hook call expressions and returns their hook name.
+ * @param node Call expression to inspect.
+ * @returns Hook name when the call targets a hook, otherwise null.
+ */
+function isHookCall(node) {
+    const hookName = getHookNameFromCallee(node.callee);
+    return hookName && isHookName(hookName) ? hookName : null;
+}
+/**
+ * Maps literal node types to memoization metadata used for reporting.
+ * @param node Candidate literal node.
+ * @returns Descriptor with literal type and memo hook, or null.
+ */
+function getLiteralDescriptor(node) {
+    const descriptor = LITERAL_DESCRIPTOR_BY_TYPE[node.type] ?? null;
+    return descriptor;
+}
+/**
+ * Finds the nearest ancestor function considered a React component or hook.
+ * @param node Starting node for the search.
+ * @returns Owning component/hook function or null.
+ */
+function findEnclosingComponentOrHook(node) {
+    let current = node.parent;
+    while (current) {
+        if (isFunctionNode(current) && isComponentOrHookFunction(current)) {
+            return current;
+        }
+        current = current.parent;
+    }
+    return null;
+}
+/**
+ * Checks whether a node is inside an allowed hook callback that should be skipped.
+ * @param node Starting node for traversal.
+ * @returns True when enclosed by a callback to an allowed hook.
+ */
+function isInsideAllowedHookCallback(node) {
+    let current = node;
+    while (current) {
+        if (current.type === utils_1.AST_NODE_TYPES.FunctionExpression ||
+            current.type === utils_1.AST_NODE_TYPES.ArrowFunctionExpression) {
+            let parent = current.parent;
+            while (parent && isExpressionWrapper(parent)) {
+                parent = parent.parent;
+            }
+            if (parent?.type === utils_1.AST_NODE_TYPES.CallExpression) {
+                const hookName = getHookNameFromCallee(parent.callee);
+                const matchesCallback = parent.arguments.some((arg) => unwrapNestedExpressions(arg) === current);
+                if (hookName && SAFE_HOOK_ARGUMENTS.has(hookName) && matchesCallback) {
+                    return true;
+                }
+            }
+        }
+        current = current.parent;
+    }
+    return false;
+}
+/**
+ * Type guard for nodes that wrap an underlying expression (e.g. assertions,
+ * parentheses, optional chaining wrappers).
+ */
+function isExpressionWrapper(node) {
+    return (node.type === utils_1.AST_NODE_TYPES.TSAsExpression ||
+        node.type === utils_1.AST_NODE_TYPES.TSTypeAssertion ||
+        node.type === utils_1.AST_NODE_TYPES.TSSatisfiesExpression ||
+        node.type === utils_1.AST_NODE_TYPES.TSNonNullExpression ||
+        node.type === utils_1.AST_NODE_TYPES.ChainExpression ||
+        isParenthesizedExpression(node));
+}
+/**
+ * Unwraps TypeScript assertions, optional chaining, and parentheses to reach
+ * the underlying expression node for stable identity comparisons.
+ */
+function unwrapNestedExpressions(node) {
+    let current = node;
+    while (isExpressionWrapper(current)) {
+        current = current.expression;
+    }
+    return current;
+}
+/**
+ * Finds the nearest enclosing hook call for a literal and whether the literal
+ * is passed directly as an argument (versus nested inside another expression).
+ */
+function findEnclosingHookCall(node) {
+    const unwrappedTarget = unwrapNestedExpressions(node);
+    let current = node.parent;
+    while (current) {
+        if (current.type === utils_1.AST_NODE_TYPES.CallExpression) {
+            const hookName = isHookCall(current);
+            if (hookName) {
+                const isDirectArgument = current.arguments.some((arg) => {
+                    const unwrappedArg = unwrapNestedExpressions(arg);
+                    return unwrappedArg === unwrappedTarget;
+                });
+                return { hookName, isDirectArgument };
+            }
+        }
+        current = current.parent;
+    }
+    return null;
+}
+/**
+ * Finds the nearest owning function for the provided node.
+ * @param node Node to start from.
+ * @returns Enclosing function declaration/expression or null.
+ */
+function findOwningFunction(node) {
+    let current = node.parent;
+    while (current) {
+        if (isFunctionNode(current)) {
+            return current;
+        }
+        current = current.parent;
+    }
+    return null;
+}
+/**
+ * Locates the closest return statement ancestor, skipping assertion wrappers.
+ * @param node Node to start from.
+ * @returns Enclosing return statement or null.
+ */
+function findEnclosingReturnStatement(node) {
+    let current = node.parent;
+    while (current) {
+        if (current.type === utils_1.AST_NODE_TYPES.ReturnStatement) {
+            return current;
+        }
+        if (isExpressionWrapper(current)) {
+            current = current.parent;
+            continue;
+        }
+        break;
+    }
+    return null;
+}
+/**
+ * Determines whether a node is returned from the provided hook function.
+ * @param node Expression candidate for return.
+ * @param owner Hook function candidate.
+ * @returns True when the expression is the hook's return value.
+ */
+function isReturnValueFromHook(node, owner) {
+    if (!isHookFunction(owner))
+        return false;
+    if (owner.type === utils_1.AST_NODE_TYPES.ArrowFunctionExpression &&
+        owner.body.type !== utils_1.AST_NODE_TYPES.BlockStatement &&
+        unwrapNestedExpressions(owner.body) === unwrapNestedExpressions(node)) {
+        return true;
+    }
+    if (node.parent?.type !== utils_1.AST_NODE_TYPES.ReturnStatement ||
+        node.parent.argument !== node) {
+        const returnStatement = findEnclosingReturnStatement(node);
+        if (!returnStatement?.argument) {
+            return false;
+        }
+        if (unwrapNestedExpressions(returnStatement.argument) !==
+            unwrapNestedExpressions(node)) {
+            return false;
+        }
+        const owningFunction = findOwningFunction(returnStatement);
+        return owningFunction === owner;
+    }
+    const owningFunction = findOwningFunction(node.parent);
+    return owningFunction === owner;
+}
+/**
+ * Builds memoization suggestions with dependency placeholders for developers.
+ * @param node Literal node to wrap.
+ * @param descriptor Literal metadata including memo hook.
+ * @param sourceCode Source code utility for text extraction.
+ * @returns Suggestion array encouraging memoization with explicit deps TODO.
+ */
+function buildMemoSuggestions(node, descriptor, sourceCode) {
+    const initializerText = sourceCode.getText(node);
+    const wrappedInitializer = descriptor.literalType === 'object literal'
+        ? `(${initializerText})`
+        : initializerText;
+    if (descriptor.literalType === 'inline function') {
+        return [
+            {
+                messageId: 'memoizeLiteralSuggestion',
+                data: {
+                    literalType: descriptor.literalType,
+                    memoHook: descriptor.memoHook,
+                },
+                fix(fixer) {
+                    return fixer.replaceText(node, `${descriptor.memoHook}(${initializerText}, [${TODO_DEPS_COMMENT}])`);
+                },
+            },
+        ];
+    }
+    return [
+        {
+            messageId: 'memoizeLiteralSuggestion',
+            data: {
+                literalType: descriptor.literalType,
+                memoHook: descriptor.memoHook,
+            },
+            fix(fixer) {
+                return fixer.replaceText(node, `${descriptor.memoHook}(() => ${wrappedInitializer}, [${TODO_DEPS_COMMENT}])`);
+            },
+        },
+    ];
+}
+/**
+ * Formats a readable label for diagnostics based on the owning function.
+ * @param fn Owning component or hook function.
+ * @returns Human-friendly label for error messages.
+ */
+function formatContextLabel(fn) {
+    const name = getFunctionName(fn);
+    if (!name)
+        return 'this component or hook';
+    if (isHookName(name))
+        return `hook "${name}"`;
+    return `component "${name}"`;
+}
+exports.reactMemoizeLiterals = (0, createRule_1.createRule)({
+    name: 'react-memoize-literals',
+    meta: {
+        type: 'suggestion',
+        docs: {
+            description: 'Detect object, array, and function literals created in React components or hooks that create new references every render. Prefer memoized values (useMemo/useCallback) or module-level constants to keep referential stability.',
+            recommended: 'error',
+        },
+        hasSuggestions: true,
+        schema: [],
+        messages: {
+            componentLiteral: 'New {{literalType}} inside {{context}} is created on every render → Breaks referential stability for hooks/props and can re-run effects or re-render children → Hoist it to a module-level constant or wrap it in {{memoHook}} with the right dependencies.',
+            nestedHookLiteral: 'Nested {{literalType}} inside {{hookName}} arguments is recreated on every render → Dependency/reference comparisons change each time and defeat memoization/caching → Extract it into a memoized value (useMemo/useCallback) or hoist it to a module constant before passing it to {{hookName}}.',
+            hookReturnLiteral: '{{hookName}} returns a {{literalType}} literal on each render → Callers receive a fresh reference and may re-render or re-run effects → Memoize the returned value with useMemo/useCallback or return pre-memoized pieces so callers see stable references.',
+            memoizeLiteralSuggestion: 'This {{literalType}} is created inline → It produces a new reference each render → Wrap it in {{memoHook}} and include every closed-over value in the dependency array.',
+        },
+    },
+    defaultOptions: [],
+    create(context) {
+        const sourceCode = context.getSourceCode();
+        function reportLiteral(node) {
+            const descriptor = getLiteralDescriptor(node);
+            if (!descriptor)
+                return;
+            if (isInsideAllowedHookCallback(node)) {
+                return;
+            }
+            const owner = findEnclosingComponentOrHook(node);
+            if (!owner)
+                return;
+            const hookCall = findEnclosingHookCall(node);
+            if (hookCall) {
+                if (hookCall.isDirectArgument) {
+                    // Top-level literal passed directly to a hook argument is allowed.
+                    return;
+                }
+                context.report({
+                    node,
+                    messageId: 'nestedHookLiteral',
+                    data: {
+                        literalType: descriptor.literalType,
+                        hookName: hookCall.hookName,
+                    },
+                });
+                return;
+            }
+            if (isReturnValueFromHook(node, owner)) {
+                const hookName = getFunctionName(owner) ?? 'this hook';
+                context.report({
+                    node,
+                    messageId: 'hookReturnLiteral',
+                    data: {
+                        literalType: descriptor.literalType,
+                        hookName,
+                    },
+                });
+                return;
+            }
+            const contextLabel = formatContextLabel(owner);
+            // Only emit auto-fix suggestions for simple variable initializers; other
+            // contexts (returns, JSX props, nested expressions) risk unsafe rewrites.
+            const suggestions = node.parent?.type === utils_1.AST_NODE_TYPES.VariableDeclarator &&
+                node.parent.init === node
+                ? buildMemoSuggestions(node, descriptor, sourceCode)
+                : undefined;
+            context.report({
+                node,
+                messageId: 'componentLiteral',
+                data: {
+                    literalType: descriptor.literalType,
+                    context: contextLabel,
+                    memoHook: descriptor.memoHook,
+                },
+                suggest: suggestions,
+            });
+        }
+        return {
+            ObjectExpression: reportLiteral,
+            ArrayExpression: reportLiteral,
+            ArrowFunctionExpression: reportLiteral,
+            FunctionExpression: reportLiteral,
+            FunctionDeclaration: reportLiteral,
+        };
+    },
+});
+//# sourceMappingURL=react-memoize-literals.js.map

package/lib/rules/react-usememo-should-be-component.js

@@ -47,7 +47,7 @@ const isUsedAsComponentProp = (context, variableName, node) => {
             break;
         }
     }
-    const sourceCode = context.getSourceCode();
+    const sourceCode = context.sourceCode;
     const scopeManager = sourceCode.scopeManager;
     const scope = scopeManager &&
         ((fn && scopeManager.acquire(fn)) || scopeManager.acquire(node));
@@ -75,7 +75,7 @@ const isUsedAsComponentProp = (context, variableName, node) => {
 const isUsedAsJsxChild = (context, variableName, node) => {
     // Traverse the nearest function (or program) to see if the identifier appears
     // as a JSX child expression.
-    const sourceCode = context.getSourceCode();
+    const sourceCode = context.sourceCode;
     let container = sourceCode.ast;
     let current = node;
     while (current?.parent) {

package/lib/rules/require-hooks-default-params.js

@@ -14,7 +14,7 @@ exports.requireHooksDefaultParams = (0, createRule_1.createRule)({
         fixable: 'code',
         schema: [],
         messages: {
-            requireDefaultParams: 'React hooks with all optional parameters should default to an empty object',
+            requireDefaultParams: 'Hook "{{hookName}}" accepts an options object where every property is optional, but the parameter is not defaulted. When callers omit the argument the hook receives undefined, so destructuring or property access throws even though the fields are optional. Default the parameter to an empty object (e.g., "({ option } = {})") so the hook stays safe to call with no arguments.',
         },
     },
     defaultOptions: [],
@@ -81,8 +81,10 @@ exports.requireHooksDefaultParams = (0, createRule_1.createRule)({
             'ArrowFunctionExpression, FunctionDeclaration'(node) {
                 // Check if it's a hook function
                 let isHook = false;
+                let hookName;
                 if (node.type === utils_1.AST_NODE_TYPES.FunctionDeclaration) {
-                    isHook = node.id ? isHookName(node.id.name) : false;
+                    hookName = node.id?.name;
+                    isHook = hookName ? isHookName(hookName) : false;
                 }
                 else {
                     const parent = node.parent;
@@ -90,12 +92,14 @@ exports.requireHooksDefaultParams = (0, createRule_1.createRule)({
                         parent.type === utils_1.AST_NODE_TYPES.VariableDeclarator &&
                         parent.id &&
                         parent.id.type === utils_1.AST_NODE_TYPES.Identifier) {
+                        hookName = parent.id.name;
                         isHook = isHookName(parent.id.name);
                     }
                 }
                 if (!isHook) {
                     return;
                 }
+                const messageData = { hookName: hookName ?? 'this hook' };
                 // Check if it has exactly one parameter
                 if (node.params.length !== 1) {
                     return;
@@ -121,10 +125,9 @@ exports.requireHooksDefaultParams = (0, createRule_1.createRule)({
                                         context.report({
                                             node: param,
                                             messageId: 'requireDefaultParams',
+                                            data: messageData,
                                             fix(fixer) {
-                                                const paramText = context
-                                                    .getSourceCode()
-                                                    .getText(param);
+                                                const paramText = context.sourceCode.getText(param);
                                                 return fixer.replaceText(param, `${paramText} = {}`);
                                             },
                                         });
@@ -140,10 +143,9 @@ exports.requireHooksDefaultParams = (0, createRule_1.createRule)({
                                         context.report({
                                             node: param,
                                             messageId: 'requireDefaultParams',
+                                            data: messageData,
                                             fix(fixer) {
-                                                const paramText = context
-                                                    .getSourceCode()
-                                                    .getText(param);
+                                                const paramText = context.sourceCode.getText(param);
                                                 return fixer.replaceText(param, `${paramText} = {}`);
                                             },
                                         });
@@ -152,7 +154,7 @@ exports.requireHooksDefaultParams = (0, createRule_1.createRule)({
                             }
                             else {
                                 // If we can't find the type definition, check if it's defined in the same file
-                                const program = context.getSourceCode().ast;
+                                const program = context.sourceCode.ast;
                                 const typeDefinitions = program.body.filter((node) => {
                                     if (node.type === utils_1.AST_NODE_TYPES.TSTypeAliasDeclaration ||
                                         node.type === utils_1.AST_NODE_TYPES.TSInterfaceDeclaration) {
@@ -172,10 +174,9 @@ exports.requireHooksDefaultParams = (0, createRule_1.createRule)({
                                             context.report({
                                                 node: param,
                                                 messageId: 'requireDefaultParams',
+                                                data: messageData,
                                                 fix(fixer) {
-                                                    const paramText = context
-                                                        .getSourceCode()
-                                                        .getText(param);
+                                                    const paramText = context.sourceCode.getText(param);
                                                     return fixer.replaceText(param, `${paramText} = {}`);
                                                 },
                                             });
@@ -191,10 +192,9 @@ exports.requireHooksDefaultParams = (0, createRule_1.createRule)({
                                             context.report({
                                                 node: param,
                                                 messageId: 'requireDefaultParams',
+                                                data: messageData,
                                                 fix(fixer) {
-                                                    const paramText = context
-                                                        .getSourceCode()
-                                                        .getText(param);
+                                                    const paramText = context.sourceCode.getText(param);
                                                     return fixer.replaceText(param, `${paramText} = {}`);
                                                 },
                                             });
@@ -214,8 +214,9 @@ exports.requireHooksDefaultParams = (0, createRule_1.createRule)({
                             context.report({
                                 node: param,
                                 messageId: 'requireDefaultParams',
+                                data: messageData,
                                 fix(fixer) {
-                                    const paramText = context.getSourceCode().getText(param);
+                                    const paramText = context.sourceCode.getText(param);
                                     return fixer.replaceText(param, `${paramText} = {}`);
                                 },
                             });

package/lib/rules/require-https-error-cause.d.ts

@@ -0,0 +1,4 @@
+import { TSESLint } from '@typescript-eslint/utils';
+type MessageIds = 'missingCause' | 'causeNotCatchBinding' | 'missingCatchBinding';
+export declare const requireHttpsErrorCause: TSESLint.RuleModule<MessageIds, [], TSESLint.RuleListener>;
+export {};