@blumintinc/eslint-plugin-blumint 1.15.0 → 1.16.1

package/lib/rules/prefer-use-deep-compare-memo.js

@@ -60,8 +60,6 @@ function isNonPrimitiveWithoutTypes(expr) {
     switch (expr.type) {
         case utils_1.AST_NODE_TYPES.ArrayExpression:
         case utils_1.AST_NODE_TYPES.ObjectExpression:
-        case utils_1.AST_NODE_TYPES.FunctionExpression:
-        case utils_1.AST_NODE_TYPES.ArrowFunctionExpression:
         case utils_1.AST_NODE_TYPES.NewExpression:
         case utils_1.AST_NODE_TYPES.ClassExpression:
             return true;
@@ -74,6 +72,8 @@ function isNonPrimitiveWithoutTypes(expr) {
         case utils_1.AST_NODE_TYPES.MemberExpression:
         case utils_1.AST_NODE_TYPES.ChainExpression:
         case utils_1.AST_NODE_TYPES.CallExpression:
+        case utils_1.AST_NODE_TYPES.FunctionExpression:
+        case utils_1.AST_NODE_TYPES.ArrowFunctionExpression:
         default:
             return false;
     }
@@ -92,9 +92,9 @@ function isNonPrimitiveWithTypes(context, expr) {
         if (!tsNode)
             return false;
         const type = checker.getTypeAtLocation(tsNode);
-        // Only consider explicit functions as non-primitive here
+        // Explicitly ignore functions even though they are non-primitive
         if (type.getCallSignatures().length > 0)
-            return true;
+            return false;
         // Avoid guessing for unknown/any or non-function types
         if (type.flags & (ts.TypeFlags.Any | ts.TypeFlags.Unknown))
             return false;
@@ -243,7 +243,7 @@ function isImportedIdentifier(context, name) {
     }
     return false;
 }
-function identifierUsedAsObjectOrFunction(callback, name) {
+function identifierUsedAsObjectOrArray(callback, name) {
     const stack = [callback.body];
     while (stack.length) {
         const node = stack.pop();
@@ -268,12 +268,6 @@ function identifierUsedAsObjectOrFunction(callback, name) {
                 }
             }
         }
-        if (node.type === utils_1.AST_NODE_TYPES.CallExpression) {
-            const callee = node.callee;
-            if (callee.type === utils_1.AST_NODE_TYPES.Identifier && callee.name === name) {
-                return true; // function usage
-            }
-        }
         if (node.type === utils_1.AST_NODE_TYPES.JSXSpreadAttribute) {
             if (node.argument.type === utils_1.AST_NODE_TYPES.Identifier &&
                 node.argument.name === name) {
@@ -313,13 +307,13 @@ exports.preferUseDeepCompareMemo = (0, createRule_1.createRule)({
     meta: {
         type: 'suggestion',
         docs: {
-            description: 'Enforce using useDeepCompareMemo when dependency array contains non-primitive values (objects, arrays, functions) that are not already memoized. This prevents unnecessary re-renders due to reference changes.',
+            description: 'Enforce using useDeepCompareMemo when dependency array contains non-primitive values (objects, arrays) that are not already memoized. This prevents unnecessary re-renders due to reference changes.',
             recommended: 'error',
         },
         fixable: 'code',
         schema: [],
         messages: {
-            preferUseDeepCompareMemo: 'Dependency array for "{{hook}}" includes objects/arrays/functions that change identity each render, so React treats them as changed and reruns the memoized computation, triggering avoidable renders. Use useDeepCompareMemo (or memoize those dependencies first) so comparisons use deep equality and the memo stays stable.',
+            preferUseDeepCompareMemo: 'Dependency array for "{{hook}}" includes objects/arrays that change identity each render, so React treats them as changed and reruns the memoized computation, triggering avoidable renders. Use useDeepCompareMemo (or memoize those dependencies first) so comparisons use deep equality and the memo stays stable.',
         },
     },
     defaultOptions: [],
@@ -366,7 +360,7 @@ exports.preferUseDeepCompareMemo = (0, createRule_1.createRule)({
                         if (isImportedIdentifier(context, expr.name)) {
                             isNonPrimitive = false;
                         }
-                        else if (identifierUsedAsObjectOrFunction(callback, expr.name) &&
+                        else if (identifierUsedAsObjectOrArray(callback, expr.name) &&
                             !isIdentifierMemoizedAbove(expr.name, memoizedIds)) {
                             isNonPrimitive = true;
                         }

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

@@ -46,6 +46,22 @@ const SAFE_HOOK_ARGUMENTS = new Set([
     'useDeepCompareEffect',
     'useProgressionCallback',
 ]);
+/**
+ * Hooks where any literal defined inside their arguments is safe because
+ * the hook either doesn't use the identity for comparison or provides its
+ * own stability.
+ */
+const HOOKS_ALLOWING_NESTED_LITERALS = new Set([
+    'useState',
+    'useReducer',
+    'useRef',
+]);
+/**
+ * JSX attribute names whose values are style descriptors consumed by the
+ * library (not via referential equality), so inline object literals are safe.
+ * MUI's `sx` and the standard `style` prop both fall into this category.
+ */
+const STYLE_JSX_ATTRIBUTE_NAMES = new Set(['sx', 'style']);
 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 ??
@@ -409,6 +425,66 @@ function buildMemoSuggestions(node, descriptor, sourceCode) {
         },
     ];
 }
+/**
+ * Returns true when the node's value resolves to a JSX attribute that carries
+ * style data consumed by a library rather than compared by reference (MUI `sx`
+ * or the standard `style` prop).
+ *
+ * Walks up from the literal only through positions where it remains the
+ * attribute's resolved value: conditional branches (`sx={c ? {…} : {…}}`),
+ * logical fallbacks (`sx={c && {…}}`), array entries (MUI accepts `sx` arrays),
+ * and expression wrappers (`{…} as const`, parentheses). Any other parent — a
+ * function call, an object property, a spread — means the reference is observed
+ * or transformed before reaching the attribute, so the walk stops and the
+ * literal stays reported. This keeps the exemption tied to genuine style values
+ * without silencing unrelated literals that merely appear deeper in the tree.
+ */
+function isStyleJSXAttributeValue(node) {
+    let current = node;
+    let parent = current.parent;
+    while (parent) {
+        switch (parent.type) {
+            case utils_1.AST_NODE_TYPES.JSXExpressionContainer: {
+                if (parent.expression !== current) {
+                    return false;
+                }
+                const attribute = parent.parent;
+                if (!attribute || attribute.type !== utils_1.AST_NODE_TYPES.JSXAttribute) {
+                    return false;
+                }
+                const { name } = attribute;
+                return (name.type === utils_1.AST_NODE_TYPES.JSXIdentifier &&
+                    STYLE_JSX_ATTRIBUTE_NAMES.has(name.name));
+            }
+            case utils_1.AST_NODE_TYPES.ConditionalExpression: {
+                if (parent.consequent !== current && parent.alternate !== current) {
+                    return false;
+                }
+                break;
+            }
+            case utils_1.AST_NODE_TYPES.LogicalExpression: {
+                if (parent.left !== current && parent.right !== current) {
+                    return false;
+                }
+                break;
+            }
+            case utils_1.AST_NODE_TYPES.ArrayExpression: {
+                if (!parent.elements.some((element) => element === current)) {
+                    return false;
+                }
+                break;
+            }
+            default: {
+                if (!isExpressionWrapper(parent) || parent.expression !== current) {
+                    return false;
+                }
+            }
+        }
+        current = parent;
+        parent = current.parent;
+    }
+    return false;
+}
 /**
  * Formats a readable label for diagnostics based on the owning function.
  * @param fn Owning component or hook function.
@@ -556,10 +632,20 @@ exports.reactMemoizeLiterals = (0, createRule_1.createRule)({
             if (isTerminalUsage(node)) {
                 return;
             }
+            // Inline literals that resolve to a style JSX attribute (sx, style),
+            // whether directly or via conditional/logical/array wrappers, are
+            // consumed by the library without reference equality checks, so
+            // memoization adds no stability benefit.
+            if (isStyleJSXAttributeValue(node)) {
+                return;
+            }
             const hookCall = findEnclosingHookCall(node);
             if (hookCall) {
-                if (hookCall.isDirectArgument) {
+                if (hookCall.isDirectArgument ||
+                    HOOKS_ALLOWING_NESTED_LITERALS.has(hookCall.hookName)) {
                     // Top-level literal passed directly to a hook argument is allowed.
+                    // Also allow nested literals for hooks that don't rely on argument
+                    // reference stability for memoization (e.g. useState, useReducer).
                     return;
                 }
                 context.report({

package/lib/rules/require-memo.js

@@ -6,6 +6,11 @@ exports.requireMemo = void 0;
 const utils_1 = require("@typescript-eslint/utils");
 const ASTHelpers_1 = require("../utils/ASTHelpers");
 const isComponentExplicitlyUnmemoized = (componentName) => componentName.toLowerCase().includes('unmemoized');
+// React's universal convention: only PascalCase-initial identifiers are
+// treated as components. camelCase names are render-prop callbacks or plain
+// helper functions that are invoked directly (e.g. MUI's renderCell(params)),
+// NOT React components — wrapping them in memo() would break callers.
+const startsWithUppercase = (name) => /^[A-Z]/.test(name);
 function isFunction(node) {
     return (node.type === utils_1.AST_NODE_TYPES.ArrowFunctionExpression ||
         node.type === utils_1.AST_NODE_TYPES.FunctionExpression ||
@@ -33,18 +38,21 @@ function isHigherOrderFunctionReturningJSX(node, context) {
 const isUnmemoizedArrowFunction = (parentNode) => {
     return (parentNode.type === 'VariableDeclarator' &&
         parentNode.id.type === 'Identifier' &&
+        startsWithUppercase(parentNode.id.name) &&
         !isComponentExplicitlyUnmemoized(parentNode.id.name));
 };
 const isUnmemoizedFunctionComponent = (parentNode, node) => {
     return (node.type === 'FunctionDeclaration' &&
         parentNode.type === 'Program' &&
         node.id &&
+        startsWithUppercase(node.id.name) &&
         !isComponentExplicitlyUnmemoized(node.id.name));
 };
 const isUnmemoizedExportedFunctionComponent = (parentNode, node) => {
     return (node.type === 'FunctionDeclaration' &&
         parentNode.type === 'ExportNamedDeclaration' &&
         node.id &&
+        startsWithUppercase(node.id.name) &&
         !isComponentExplicitlyUnmemoized(node.id.name));
 };
 function isMemoImport(importPath) {

package/lib/rules/require-migration-script-metadata.d.ts

@@ -0,0 +1,9 @@
+type MessageIds = 'missingMetadata' | 'metadataAfterStatement' | 'missingMigrationTag' | 'invalidMigrationTag' | 'missingPhaseTag' | 'invalidPhaseTag' | 'missingDependenciesTag' | 'invalidDependenciesTag' | 'missingDescriptionTag' | 'extensionInDependencies' | 'noneCasing' | 'legacyHeaderNotAllowed' | 'multipleMetadataBlocks';
+type Options = [
+    {
+        targetGlobs?: string[];
+        allowLegacyHeader?: boolean;
+    }
+];
+export declare const requireMigrationScriptMetadata: import("@typescript-eslint/utils/dist/ts-eslint/Rule").RuleModule<MessageIds, Options, import("@typescript-eslint/utils/dist/ts-eslint/Rule").RuleListener>;
+export {};

package/lib/rules/require-migration-script-metadata.js

@@ -0,0 +1,206 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.requireMigrationScriptMetadata = void 0;
+const minimatch_1 = require("minimatch");
+const createRule_1 = require("../utils/createRule");
+const DEFAULT_OPTIONS = {
+    targetGlobs: ['**/functions/src/callable/scripts/**/*.f.ts'],
+    allowLegacyHeader: true,
+};
+exports.requireMigrationScriptMetadata = (0, createRule_1.createRule)({
+    name: 'require-migration-script-metadata',
+    meta: {
+        type: 'suggestion',
+        docs: {
+            description: 'Enforce JSDoc migration metadata in callable scripts',
+            recommended: 'error',
+        },
+        schema: [
+            {
+                type: 'object',
+                properties: {
+                    targetGlobs: {
+                        type: 'array',
+                        items: { type: 'string' },
+                    },
+                    allowLegacyHeader: {
+                        type: 'boolean',
+                    },
+                },
+                additionalProperties: false,
+            },
+        ],
+        messages: {
+            missingMetadata: 'Missing migration metadata JSDoc block → Release tooling cannot determine participation or ordering, which can skip or misorder migrations → Add a top-of-file JSDoc block with `@migration` true/false; when true include `@migrationPhase`, `@migrationDependencies` (or NONE), and `@migrationDescription`.',
+            metadataAfterStatement: 'Migration metadata appears after code/imports → The release scanner only reads the top-of-file block and will miss this metadata → Move the metadata JSDoc above all imports/statements (legacy header allowed only when configured).',
+            missingMigrationTag: 'Metadata block is missing `@migration` → Without an explicit true/false, automation cannot decide whether to run this script → Add `@migration` true or `@migration` false to the metadata block.',
+            invalidMigrationTag: 'Invalid `@migration` value → Only true/false is supported so automation can branch deterministically → Replace with `@migration` true or `@migration` false.',
+            missingPhaseTag: 'Missing `@migrationPhase` while `@migration` is true → Release ordering cannot place this script → Add `@migrationPhase` before or after.',
+            invalidPhaseTag: 'Invalid `@migrationPhase` value → Release ordering only understands before/after → Use `@migrationPhase` before or `@migrationPhase` after.',
+            missingDependenciesTag: 'Missing `@migrationDependencies` while `@migration` is true → Dependency ordering cannot be computed → Add `@migrationDependencies` NONE or a comma-separated list of script names.',
+            invalidDependenciesTag: 'Invalid `@migrationDependencies` list → Empty or whitespace entries break dependency resolution → Provide a comma-separated list of non-empty names or NONE.',
+            missingDescriptionTag: 'Missing `@migrationDescription` while `@migration` is true → Release reports lose context and reviewers cannot assess impact → Add a brief `@migrationDescription`.',
+            extensionInDependencies: 'Dependency "{{name}}" includes a file extension → Dependencies are script identifiers, and extensions cause mismatches → Remove the ".f.ts" extension from "{{name}}".',
+            noneCasing: 'Invalid `@migrationDependencies` casing → Automation expects exactly "NONE" in all-caps to signal no dependencies → Change to uppercase "NONE".',
+            legacyHeaderNotAllowed: 'Legacy header/comment appears before metadata → The metadata block must be the first file-level block to keep linting deterministic → Remove leading comments or enable allowLegacyHeader.',
+            multipleMetadataBlocks: 'Multiple metadata blocks found → Conflicting `@migration` tags make automation ambiguous → Keep exactly one JSDoc block with `@migration`.',
+        },
+    },
+    defaultOptions: [DEFAULT_OPTIONS],
+    create(context, [options]) {
+        const rawFilename = context.filename ?? context.getFilename();
+        const filename = rawFilename.replace(/\\/g, '/');
+        const { targetGlobs, allowLegacyHeader } = {
+            ...DEFAULT_OPTIONS,
+            ...options,
+        };
+        // Only run on files matching targetGlobs
+        const isTargetFile = targetGlobs?.some((glob) => (0, minimatch_1.minimatch)(filename, glob, { dot: true, matchBase: true }));
+        if (!isTargetFile) {
+            return {};
+        }
+        const sourceCode = context.sourceCode ?? context.getSourceCode();
+        const comments = sourceCode.getAllComments();
+        const firstToken = sourceCode.getFirstToken(sourceCode.ast, {
+            includeComments: false,
+        });
+        return {
+            Program() {
+                const metadataCandidates = comments
+                    .filter((comment) => comment.type === 'Block' && comment.value.startsWith('*'))
+                    .map((comment) => ({ comment, tags: parseJSDocTags(comment.value) }))
+                    .filter(({ tags }) => Object.keys(tags).some((tag) => tag.startsWith('migration')));
+                if (metadataCandidates.length > 1) {
+                    for (const extra of metadataCandidates.slice(1)) {
+                        context.report({
+                            node: extra.comment,
+                            messageId: 'multipleMetadataBlocks',
+                        });
+                    }
+                }
+                const migrationMetadata = metadataCandidates[0] ?? null;
+                if (!migrationMetadata) {
+                    context.report({
+                        loc: { line: 1, column: 0 },
+                        messageId: 'missingMetadata',
+                    });
+                    return;
+                }
+                const { comment, tags } = migrationMetadata;
+                if (!allowLegacyHeader) {
+                    const hasLeadingComment = comments.some((c) => c.type === 'Block' && c.range[0] < comment.range[0]);
+                    if (hasLeadingComment) {
+                        context.report({
+                            node: comment,
+                            messageId: 'legacyHeaderNotAllowed',
+                        });
+                    }
+                }
+                // Check if metadata appears after the first statement/import
+                if (firstToken && comment.range[0] > firstToken.range[0]) {
+                    context.report({
+                        node: comment,
+                        messageId: 'metadataAfterStatement',
+                    });
+                }
+                if (!('migration' in tags)) {
+                    context.report({
+                        node: comment,
+                        messageId: 'missingMigrationTag',
+                    });
+                    return;
+                }
+                const migration = tags.migration;
+                if (migration !== 'true' && migration !== 'false') {
+                    context.report({
+                        node: comment,
+                        messageId: 'invalidMigrationTag',
+                    });
+                    return;
+                }
+                if (migration === 'true') {
+                    // Check phase
+                    if (!tags.migrationPhase) {
+                        context.report({
+                            node: comment,
+                            messageId: 'missingPhaseTag',
+                        });
+                    }
+                    else if (tags.migrationPhase !== 'before' &&
+                        tags.migrationPhase !== 'after') {
+                        context.report({
+                            node: comment,
+                            messageId: 'invalidPhaseTag',
+                        });
+                    }
+                    // Check dependencies
+                    if (!tags.migrationDependencies) {
+                        context.report({
+                            node: comment,
+                            messageId: 'missingDependenciesTag',
+                        });
+                    }
+                    else {
+                        const deps = tags.migrationDependencies
+                            .split(',')
+                            .map((d) => d.trim());
+                        const hasNone = deps.some((d) => d.toUpperCase() === 'NONE');
+                        if (deps.some((d) => d === '')) {
+                            context.report({
+                                node: comment,
+                                messageId: 'invalidDependenciesTag',
+                            });
+                        }
+                        else if (hasNone && deps.length > 1) {
+                            context.report({
+                                node: comment,
+                                messageId: 'invalidDependenciesTag',
+                            });
+                        }
+                        else if (hasNone && deps[0] !== 'NONE') {
+                            context.report({
+                                node: comment,
+                                messageId: 'noneCasing',
+                            });
+                        }
+                        else if (hasNone && deps[0] === 'NONE') {
+                            // Valid: exactly NONE
+                        }
+                        else {
+                            for (const dep of deps) {
+                                if (dep.endsWith('.f.ts')) {
+                                    context.report({
+                                        node: comment,
+                                        messageId: 'extensionInDependencies',
+                                        data: { name: dep },
+                                    });
+                                }
+                            }
+                        }
+                    }
+                    // Check description
+                    if (!tags.migrationDescription) {
+                        context.report({
+                            node: comment,
+                            messageId: 'missingDescriptionTag',
+                        });
+                    }
+                }
+            },
+        };
+    },
+});
+function parseJSDocTags(commentValue) {
+    const tags = {};
+    const lines = commentValue.split('\n');
+    for (const line of lines) {
+        const trimmedLine = line.trim().replace(/^\*+\s*/, '');
+        const match = trimmedLine.match(/^@(\w+)(?:\s+(.*))?$/);
+        if (match) {
+            const [, tagName, tagValue] = match;
+            tags[tagName] = (tagValue ?? '').trim();
+        }
+    }
+    return tags;
+}
+//# sourceMappingURL=require-migration-script-metadata.js.map

package/lib/rules/warn-https-error-message-user-friendly.d.ts

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