@blumintinc/eslint-plugin-blumint 1.20.31 → 1.20.32

package/lib/index.js

@@ -223,7 +223,7 @@ function noFrontendImportsFromFunctionsPatterns(pattern) {
 module.exports = {
     meta: {
         name: '@blumintinc/eslint-plugin-blumint',
-        version: '1.20.31',
+        version: '1.20.32',
     },
     parseOptions: {
         ecmaVersion: 2020,

package/lib/rules/enforce-microdiff.d.ts

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

package/lib/rules/enforce-microdiff.js

@@ -3,6 +3,94 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.enforceMicrodiff = void 0;
 const utils_1 = require("@typescript-eslint/utils");
 const createRule_1 = require("../utils/createRule");
+const ASTHelpers_1 = require("../utils/ASTHelpers");
+const DIFF_NAME = 'diff';
+const MICRODIFF_MODULE = 'microdiff';
+/**
+ * The libraries this rule replaces. Every fix retires the whole import
+ * declaration of one of these, which is what makes the names it binds available
+ * to the microdiff import that takes its place.
+ */
+const COMPETING_DIFF_MODULES = new Set([
+    'deep-diff',
+    'fast-diff',
+    'diff',
+    'deep-object-diff',
+    // 'fast-deep-equal' and 'fast-deep-equal/es6' stay out of this set: they are
+    // allowed alternatives to microdiff, so their imports survive the fix.
+]);
+/**
+ * A specifier that makes a bare `diff` resolve to microdiff's diff function:
+ * its default export, or its named `diff` export, bound under the name the fix
+ * emits.
+ */
+function bindsMicrodiffDiff(specifier) {
+    if (specifier.local.name !== DIFF_NAME) {
+        return false;
+    }
+    if (specifier.type === utils_1.AST_NODE_TYPES.ImportDefaultSpecifier) {
+        return true;
+    }
+    return (specifier.type === utils_1.AST_NODE_TYPES.ImportSpecifier &&
+        specifier.importKind !== 'type' &&
+        specifier.imported.name === DIFF_NAME);
+}
+/**
+ * microdiff's import read off `Program.body` rather than off a flag raised by
+ * the ImportDeclaration visitor. A competing import that precedes the microdiff
+ * one is fixed before the visitor reaches microdiff, so a flag still unset at
+ * that point makes the fix emit a second `import { diff } from 'microdiff'` and
+ * duplicate the binding (TS2300). Demanding a specifier that binds `diff` also
+ * rejects the shapes a source-only test mistakes for a usable binding: a
+ * namespace import, a type-only import, and an alias of some other export.
+ */
+function findMicrodiffImport(program) {
+    return program.body.find((statement) => statement.type === utils_1.AST_NODE_TYPES.ImportDeclaration &&
+        statement.source.value === MICRODIFF_MODULE &&
+        statement.importKind !== 'type' &&
+        statement.specifiers.some(bindsMicrodiffDiff));
+}
+/**
+ * The declarations of `diff` that a fix may write over: microdiff's own
+ * specifier, which an emitted `diff` is meant to resolve to, and the specifiers
+ * of a competing library's import, which the fix replaces or removes outright.
+ * Any other declaration of the name belongs to the file's own code.
+ */
+function collectClaimableSpecifiers(program) {
+    const claimable = new Set();
+    program.body.forEach((statement) => {
+        if (statement.type !== utils_1.AST_NODE_TYPES.ImportDeclaration) {
+            return;
+        }
+        const source = statement.source.value;
+        if (source === MICRODIFF_MODULE) {
+            statement.specifiers
+                .filter(bindsMicrodiffDiff)
+                .forEach((specifier) => claimable.add(specifier));
+            return;
+        }
+        if (COMPETING_DIFF_MODULES.has(source)) {
+            statement.specifiers.forEach((specifier) => claimable.add(specifier));
+        }
+    });
+    return claimable;
+}
+/**
+ * Whether a bare `diff` written at `scope` reaches microdiff's function.
+ * Resolving through the scope chain catches both failure modes: a module-scope
+ * binding that the inserted import redeclares (TS2440, or TS2300 against
+ * another import), and a narrower shadow that captures the emitted reference
+ * with no diagnostic at all. A binding with no declaration — a global supplied
+ * by the environment — is left alone rather than written over.
+ */
+function canEmitDiff(scope, claimable) {
+    const existing = ASTHelpers_1.ASTHelpers.findVariableInScope(scope, DIFF_NAME);
+    if (!existing) {
+        return true;
+    }
+    return (existing.defs.length > 0 &&
+        existing.defs.every((def) => claimable.has(def.node)));
+}
 exports.enforceMicrodiff = (0, createRule_1.createRule)({
     name: 'enforce-microdiff',
     meta: {
@@ -23,8 +111,31 @@ exports.enforceMicrodiff = (0, createRule_1.createRule)({
         const sourceCode = context.sourceCode;
         const importedDiffLibraries = new Map();
         const importedFunctions = new Map(); // Map of imported function names to their sources
-        let hasMicrodiffImport = false;
         const reportedNodes = new Set();
+        /**
+         * Whether the fix may emit a bare `diff` at `node`. The AST is read at fix
+         * time so the answer stays correct under multi-pass `--fix`, where an
+         * earlier pass may already have added the microdiff import.
+         */
+        function canEmitDiffAt(node) {
+            return canEmitDiff(ASTHelpers_1.ASTHelpers.getScope(context, node), collectClaimableSpecifiers(sourceCode.ast));
+        }
+        /**
+         * Whether retiring `declaration` leaves every reference it binds able to
+         * take the name `diff`. The import rewrite lands at module scope while the
+         * references it serves sit in nested scopes: one standing where `diff` is
+         * shadowed keeps the old name, because its own fix declines, so rewriting
+         * the import would strand it without a binding (TS2304).
+         */
+        function canRenameReferencesOf(declaration) {
+            const claimable = collectClaimableSpecifiers(sourceCode.ast);
+            const declarationScope = ASTHelpers_1.ASTHelpers.getScope(context, declaration);
+            return declaration.specifiers.every((specifier) => {
+                const variable = ASTHelpers_1.ASTHelpers.findVariableInScope(declarationScope, specifier.local.name);
+                return (!variable ||
+                    variable.references.every((reference) => canEmitDiff(reference.from, claimable)));
+            });
+        }
         // Add a specific set to track which import names are used
         const usedImportNames = new Set();
         // Check if a node is an object or array type
@@ -61,19 +172,11 @@ exports.enforceMicrodiff = (0, createRule_1.createRule)({
             ImportDeclaration(node) {
                 const importSource = node.source.value;
                 // Check for microdiff import
-                if (importSource === 'microdiff') {
-                    hasMicrodiffImport = true;
+                if (importSource === MICRODIFF_MODULE) {
                     return;
                 }
                 // Track other diffing libraries
-                if ([
-                    'deep-diff',
-                    'fast-diff',
-                    'diff',
-                    'deep-object-diff',
-                    // Removed 'fast-deep-equal' and 'fast-deep-equal/es6' from this list
-                    // as they are allowed alternatives to microdiff
-                ].includes(importSource)) {
+                if (COMPETING_DIFF_MODULES.has(importSource)) {
                     // Track imported function names and their sources
                     node.specifiers.forEach((specifier) => {
                         if (specifier.type === utils_1.AST_NODE_TYPES.ImportSpecifier &&
@@ -94,12 +197,18 @@ exports.enforceMicrodiff = (0, createRule_1.createRule)({
                             importSource,
                         },
                         fix(fixer) {
+                            // Decline rather than duplicate or shadow a `diff` this file
+                            // already binds to something else. The report stands so the
+                            // author resolves the name clash deliberately.
+                            if (!canEmitDiffAt(node) || !canRenameReferencesOf(node)) {
+                                return null;
+                            }
                             // If we already have a microdiff import, just remove this import
-                            if (hasMicrodiffImport) {
+                            if (findMicrodiffImport(sourceCode.ast)) {
                                 return fixer.remove(node);
                             }
                             // Otherwise, replace with microdiff import
-                            return fixer.replaceText(node, `import { diff } from 'microdiff';`);
+                            return fixer.replaceText(node, `import { ${DIFF_NAME} } from '${MICRODIFF_MODULE}';`);
                         },
                     });
                     // Check if importing a diff function or a known equality library
@@ -154,7 +263,10 @@ exports.enforceMicrodiff = (0, createRule_1.createRule)({
                             node,
                             messageId: 'enforceMicrodiff',
                             fix(fixer) {
-                                return fixer.replaceText(callee, 'diff');
+                                if (!canEmitDiffAt(node)) {
+                                    return null;
+                                }
+                                return fixer.replaceText(callee, DIFF_NAME);
                             },
                         });
                         return;
@@ -179,8 +291,11 @@ exports.enforceMicrodiff = (0, createRule_1.createRule)({
                                 node,
                                 messageId: 'enforceMicrodiff',
                                 fix(fixer) {
+                                    if (!canEmitDiffAt(node)) {
+                                        return null;
+                                    }
                                     // When handling fast-diff and similar libraries, need to ensure the function name is replaced
-                                    return fixer.replaceText(callee, 'diff');
+                                    return fixer.replaceText(callee, DIFF_NAME);
                                 },
                             });
                         }
@@ -198,8 +313,11 @@ exports.enforceMicrodiff = (0, createRule_1.createRule)({
                             node,
                             messageId: 'enforceMicrodiff',
                             fix(fixer) {
+                                if (!canEmitDiffAt(node)) {
+                                    return null;
+                                }
                                 // Replace with microdiff
-                                return fixer.replaceText(node, `diff(${node.arguments
+                                return fixer.replaceText(node, `${DIFF_NAME}(${node.arguments
                                     .map((arg) => sourceCode.getText(arg))
                                     .join(', ')})`);
                             },
@@ -245,6 +363,9 @@ exports.enforceMicrodiff = (0, createRule_1.createRule)({
                                 node,
                                 messageId: 'enforceMicrodiff',
                                 fix(fixer) {
+                                    if (!canEmitDiffAt(node)) {
+                                        return null;
+                                    }
                                     // Find the containing function to add the import
                                     let functionNode = node;
                                     while (functionNode &&
@@ -258,15 +379,15 @@ exports.enforceMicrodiff = (0, createRule_1.createRule)({
                                     // we'll need to add the import manually
                                     if (functionNode &&
                                         functionNode.type === utils_1.AST_NODE_TYPES.Program &&
-                                        !hasMicrodiffImport) {
+                                        !findMicrodiffImport(sourceCode.ast)) {
                                         // Need to add an import
-                                        const importFix = fixer.insertTextBeforeRange([0, 0], "import { diff } from 'microdiff';\n\n");
+                                        const importFix = fixer.insertTextBeforeRange([0, 0], `import { ${DIFF_NAME} } from '${MICRODIFF_MODULE}';\n\n`);
                                         // Replace JSON.stringify comparison
-                                        const compareFix = fixer.replaceText(node, `diff(${sourceCode.getText(leftArg)}, ${sourceCode.getText(rightArg)})${isEqual ? '.length === 0' : '.length > 0'}`);
+                                        const compareFix = fixer.replaceText(node, `${DIFF_NAME}(${sourceCode.getText(leftArg)}, ${sourceCode.getText(rightArg)})${isEqual ? '.length === 0' : '.length > 0'}`);
                                         return [importFix, compareFix];
                                     }
                                     // Otherwise just replace the comparison
-                                    return fixer.replaceText(node, `diff(${sourceCode.getText(leftArg)}, ${sourceCode.getText(rightArg)})${isEqual ? '.length === 0' : '.length > 0'}`);
+                                    return fixer.replaceText(node, `${DIFF_NAME}(${sourceCode.getText(leftArg)}, ${sourceCode.getText(rightArg)})${isEqual ? '.length === 0' : '.length > 0'}`);
                                 },
                             });
                         }
@@ -308,13 +429,16 @@ exports.enforceMicrodiff = (0, createRule_1.createRule)({
                                 node,
                                 messageId: 'enforceMicrodiff',
                                 fix(fixer) {
+                                    if (!canEmitDiffAt(node)) {
+                                        return null;
+                                    }
                                     // Create a new version of the function with microdiff
                                     const newFunctionBody = `{
-  return diff(${param1}, ${param2}).length > 0;
+  return ${DIFF_NAME}(${param1}, ${param2}).length > 0;
 }`;
-                                    if (!hasMicrodiffImport) {
+                                    if (!findMicrodiffImport(sourceCode.ast)) {
                                         // Create a new import statement
-                                        return fixer.replaceText(node, `import { diff } from 'microdiff';\n\nfunction ${node.id?.name}(${param1}, ${param2}) ${newFunctionBody}`);
+                                        return fixer.replaceText(node, `import { ${DIFF_NAME} } from '${MICRODIFF_MODULE}';\n\nfunction ${node.id?.name}(${param1}, ${param2}) ${newFunctionBody}`);
                                     }
                                     else {
                                         // Just replace the function body

package/lib/rules/enforce-stable-hash-spread-props.js

@@ -146,6 +146,25 @@ function getStableHashLocalNames(sourceCode, hashImport) {
 function isStableHashImported(sourceCode, hashImport) {
     return getStableHashLocalNames(sourceCode, hashImport).length > 0;
 }
+/**
+ * Whether every declaration of a resolved binding is the configured hash import
+ * itself. A namespace import, an import of another name or module, a parameter,
+ * or a local declaration all mean the emitted call would resolve somewhere other
+ * than the intended hash function.
+ */
+function bindsHashImport(variable, hashImport) {
+    return (variable.defs.length > 0 &&
+        variable.defs.every((def) => {
+            const specifier = def.node;
+            if (specifier.type !== utils_1.AST_NODE_TYPES.ImportSpecifier ||
+                specifier.imported.name !== hashImport.importName) {
+                return false;
+            }
+            const declaration = specifier.parent;
+            return (declaration?.type === utils_1.AST_NODE_TYPES.ImportDeclaration &&
+                declaration.source.value === hashImport.source);
+        }));
+}
 function getIndentBeforeNode(sourceCode, node) {
     const lineText = sourceCode.lines[node.loc.start.line - 1] ?? '';
     const match = lineText.match(/^[ \t]*/);
@@ -222,7 +241,6 @@ exports.enforceStableHashSpreadProps = (0, createRule_1.createRule)({
         // emit `stableHash(...)`, leaving calls to an unbound identifier.
         let importPlanned = false;
         const isReportSuppressed = (0, disableDirectives_1.createSuppressionChecker)(context);
-        const hashIdentifier = existingHashLocalNames[0] ?? hashImport.importName;
         const functionStack = [];
         function getCurrentComponentContext() {
             for (let i = functionStack.length - 1; i >= 0; i -= 1) {
@@ -315,6 +333,27 @@ exports.enforceStableHashSpreadProps = (0, createRule_1.createRule)({
                         if (isReportSuppressed(depsArg)) {
                             return null;
                         }
+                        // Derive the emitted name from the file's imports rather than from
+                        // traversal state: `--fix` re-lints between passes, so an import a
+                        // previous pass landed must be reused, and an alias it introduced
+                        // must be honoured.
+                        const hashIdentifier = getStableHashLocalNames(sourceCode, hashImport)[0] ??
+                            hashImport.importName;
+                        // The fix writes a bare `hashIdentifier` call into the dependency
+                        // array and may add a top-level import for it. Another binding of
+                        // that name, visible from the array, makes both halves wrong: a
+                        // module-scope binding collides with the inserted import
+                        // (TS2440/TS2300), and a narrower shadow silently resolves the
+                        // emitted call to the wrong value with no TypeScript diagnostic at
+                        // all. Resolving through the scope chain of the reported node — the
+                        // exact position the call lands in — covers both, while a binding
+                        // that already is the desired import is the reuse path. Declining
+                        // leaves the report for the author to resolve deliberately.
+                        const existingBinding = ASTHelpers_1.ASTHelpers.findVariableInScope(ASTHelpers_1.ASTHelpers.getScope(context, depsArg), hashIdentifier);
+                        if (existingBinding &&
+                            !bindsHashImport(existingBinding, hashImport)) {
+                            return null;
+                        }
                         const fixes = [];
                         const seen = new Set();
                         for (const { node: targetNode } of offendingElements) {

package/lib/rules/fast-deep-equal-over-microdiff.js

@@ -3,7 +3,32 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.fastDeepEqualOverMicrodiff = void 0;
 const utils_1 = require("@typescript-eslint/utils");
 const createRule_1 = require("../utils/createRule");
+const ASTHelpers_1 = require("../utils/ASTHelpers");
 const disableDirectives_1 = require("../utils/disableDirectives");
+const FAST_DEEP_EQUAL_MODULES = new Set([
+    'fast-deep-equal',
+    'fast-deep-equal/es6',
+]);
+/**
+ * Whether every declaration of a visible binding is a fast-deep-equal import,
+ * i.e. the name already means the comparison function the fix wants to call.
+ * The verdict comes off the AST (each definition's specifier and its import
+ * declaration) rather than a traversal flag, so it holds on every pass of a
+ * multi-pass `--fix`, including the passes that follow an inserted import.
+ */
+function bindsFastDeepEqual(variable) {
+    return (variable.defs.length > 0 &&
+        variable.defs.every((def) => {
+            const specifier = def.node;
+            if (specifier.type !== utils_1.AST_NODE_TYPES.ImportDefaultSpecifier &&
+                specifier.type !== utils_1.AST_NODE_TYPES.ImportSpecifier) {
+                return false;
+            }
+            const declaration = specifier.parent;
+            return (declaration?.type === utils_1.AST_NODE_TYPES.ImportDeclaration &&
+                FAST_DEEP_EQUAL_MODULES.has(declaration.source.value));
+        }));
+}
 exports.fastDeepEqualOverMicrodiff = (0, createRule_1.createRule)({
     name: 'fast-deep-equal-over-microdiff',
     meta: {
@@ -306,6 +331,18 @@ exports.fastDeepEqualOverMicrodiff = (0, createRule_1.createRule)({
             if (isReportSuppressed(node)) {
                 return null;
             }
+            // A binding for the target name that is not the fast-deep-equal import
+            // makes both halves of the edit wrong: an inserted import collides with a
+            // same-scope declaration (TS2440/TS2300), and a narrower-scope shadow
+            // rebinds the emitted call to the local value with no diagnostic at all.
+            // Resolving from the fixed node's scope chain catches both. Declining
+            // before the import is scheduled leaves the carrier slot to a violation
+            // whose scope is safe, and drops the whole edit — including the removal
+            // of a redundant `const changes = diff(...)` — rather than half of it.
+            const existingBinding = ASTHelpers_1.ASTHelpers.findVariableInScope(ASTHelpers_1.ASTHelpers.getScope(context, node), fastDeepEqualImportName);
+            if (existingBinding && !bindsFastDeepEqual(existingBinding)) {
+                return null;
+            }
             const args = diffCall.arguments;
             if (args.length !== 2) {
                 return null; // Can't fix if not exactly 2 arguments

package/lib/rules/prefer-global-router-state-key.js

@@ -7,6 +7,7 @@ exports.preferGlobalRouterStateKey = void 0;
 const path_1 = __importDefault(require("path"));
 const utils_1 = require("@typescript-eslint/utils");
 const createRule_1 = require("../utils/createRule");
+const ASTHelpers_1 = require("../utils/ASTHelpers");
 // The module's path below the project root doubles as the bare specifier,
 // which is precisely why the root tsconfig `paths` and the Jest mapper resolve
 // it.
@@ -121,6 +122,35 @@ exports.preferGlobalRouterStateKey = (0, createRule_1.createRule)({
         function isValidQueryKeyConstant(name) {
             return name.startsWith('QUERY_KEY_');
         }
+        /**
+         * Whether every declaration of a visible binding is the very import the fix
+         * wants to reference: a value `ImportSpecifier` of `constant` taken from
+         * queryKeys.ts, under any local name. Read off the specifier nodes the scope
+         * points at rather than off the traversal maps, so an import written below
+         * the call site — which the `ImportDeclaration` visitor has not recorded by
+         * the time the fix runs — is recognized instead of duplicated.
+         *
+         * Any other binding (a local declaration, a parameter, an alias of a
+         * different export, a type-only specifier) means a bare reference to the
+         * name would resolve somewhere other than the constant.
+         */
+        function bindsQueryKeyConstant(variable, constant) {
+            return (variable.defs.length > 0 &&
+                variable.defs.every((def) => {
+                    const specifier = def.node;
+                    if (specifier.type !== utils_1.AST_NODE_TYPES.ImportSpecifier ||
+                        specifier.importKind === 'type' ||
+                        specifier.imported.name !== constant) {
+                        return false;
+                    }
+                    const declaration = specifier.parent;
+                    return (declaration?.type === utils_1.AST_NODE_TYPES.ImportDeclaration &&
+                        declaration.importKind !== 'type' &&
+                        declaration.source.type === utils_1.AST_NODE_TYPES.Literal &&
+                        typeof declaration.source.value === 'string' &&
+                        isQueryKeysSource(declaration.source.value));
+                }));
+        }
         /**
          * `SourceCode#getScope` supersedes the deprecated `context.getScope`; the
          * fallback keeps the rule working on ESLint versions that predate it.
@@ -361,12 +391,39 @@ exports.preferGlobalRouterStateKey = (0, createRule_1.createRule)({
                                                         const replacementText = localName
                                                             ? localName
                                                             : formatConstantReference(importAlias, suggestedConstant);
+                                                        // A binding that already owns the emitted name
+                                                        // makes both halves of the edit wrong: the inserted
+                                                        // import becomes a second declaration of it
+                                                        // (TS2440/TS2300), and a shadowing local or
+                                                        // parameter captures the bare reference with no
+                                                        // diagnostic at all. Resolving through the scope
+                                                        // chain at the literal rather than the module scope
+                                                        // is what exposes such a shadow. Declining leaves
+                                                        // the report in place for the author to resolve.
+                                                        // The qualified `alias.CONSTANT` form reaches the
+                                                        // constant through the alias and claims no name of
+                                                        // its own.
+                                                        const visibleBinding = importAlias
+                                                            ? null
+                                                            : ASTHelpers_1.ASTHelpers.findVariableInScope(ASTHelpers_1.ASTHelpers.getScope(context, keyValue), replacementText);
+                                                        const bindingIsQueryKeyImport = visibleBinding !== null &&
+                                                            bindsQueryKeyConstant(visibleBinding, suggestedConstant);
+                                                        if (visibleBinding && !bindingIsQueryKeyImport) {
+                                                            return null;
+                                                        }
                                                         // 1) Replace the literal with the constant (qualify if alias exists)
                                                         fixes.push(fixer.replaceText(keyValue, replacementText));
                                                         // 2) Ensure an import exists for the suggested constant
                                                         const hasNamespaceOrDefault = Boolean(importAlias);
                                                         if (!existingNamedImport &&
                                                             !hasNamespaceOrDefault) {
+                                                            // The name resolves to the very import this fix
+                                                            // would write — one declared below this call site,
+                                                            // which the traversal maps miss — so the
+                                                            // replacement alone is the complete edit.
+                                                            if (bindingIsQueryKeyImport) {
+                                                                return fixes;
+                                                            }
                                                             if (scheduledQueryKeyNamedImports.has(suggestedConstant)) {
                                                                 return fixes;
                                                             }

package/lib/rules/prefer-next-dynamic.js

@@ -3,6 +3,9 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.preferNextDynamic = void 0;
 const utils_1 = require("@typescript-eslint/utils");
 const createRule_1 = require("../utils/createRule");
+const ASTHelpers_1 = require("../utils/ASTHelpers");
+const NEXT_DYNAMIC_MODULE = 'next/dynamic';
+const DEFAULT_DYNAMIC_NAME = 'dynamic';
 const DEFAULT_USE_DYNAMIC_SOURCES = [
     'useDynamic',
     './useDynamic',
@@ -99,7 +102,7 @@ function findUseDynamicImport(program, allowedSources) {
 }
 function getNextDynamicLocalName(program) {
     for (const imp of getImportDeclarations(program)) {
-        if (imp.source.value === 'next/dynamic') {
+        if (imp.source.value === NEXT_DYNAMIC_MODULE) {
             const def = imp.specifiers.find((s) => s.type === utils_1.AST_NODE_TYPES.ImportDefaultSpecifier);
             if (def)
                 return def.local.name;
@@ -107,6 +110,24 @@ function getNextDynamicLocalName(program) {
     }
     return null;
 }
+/**
+ * Whether every declaration of a visible binding is the `next/dynamic` default
+ * import itself. A local variable, a function declaration, a parameter, or an
+ * import from any other module all mean the emitted call would resolve
+ * somewhere other than Next.js's `dynamic`.
+ */
+function bindsNextDynamicDefault(variable) {
+    return (variable.defs.length > 0 &&
+        variable.defs.every((def) => {
+            const specifier = def.node;
+            if (specifier.type !== utils_1.AST_NODE_TYPES.ImportDefaultSpecifier) {
+                return false;
+            }
+            const declaration = specifier.parent;
+            return (declaration?.type === utils_1.AST_NODE_TYPES.ImportDeclaration &&
+                declaration.source.value === NEXT_DYNAMIC_MODULE);
+        }));
+}
 function buildDynamicReplacement(call, variableKind, variableIdText, namedExportKey, sourceCode, dynamicIdent) {
     const expr = buildDynamicExpression(call, namedExportKey, sourceCode, dynamicIdent);
     return `${variableKind} ${variableIdText} = ${expr};`;
@@ -235,10 +256,24 @@ exports.preferNextDynamic = (0, createRule_1.createRule)({
                     data: { componentName: identifierName },
                     fix(fixer) {
                         const fixes = [];
-                        // ensure dynamic import is present
+                        // Read the import off Program.body rather than a traversal flag so
+                        // the decision stays correct across the re-lints of a multi-pass
+                        // `--fix`, where an earlier pass may already have inserted it.
                         const programNode = program;
                         let dynamicLocal = getNextDynamicLocalName(programNode);
                         const hasDynamic = !!dynamicLocal;
+                        // Resolve the identifier the replacement will emit through the
+                        // scope chain at the fix site. Any binding that is not the
+                        // `next/dynamic` default import makes the edit wrong: an inserted
+                        // import collides with a same-named declaration (TS2440/TS2300),
+                        // and a narrower-scope shadow silently binds the emitted call to
+                        // the shadow with no TypeScript diagnostic at all. Declining leaves
+                        // the report for the author to resolve deliberately.
+                        const emittedName = dynamicLocal ?? DEFAULT_DYNAMIC_NAME;
+                        const existing = ASTHelpers_1.ASTHelpers.findVariableInScope(ASTHelpers_1.ASTHelpers.getScope(context, init), emittedName);
+                        if (existing && !bindsNextDynamicDefault(existing)) {
+                            return null;
+                        }
                         if (!hasDynamic) {
                             // Insert after directive prologue (e.g., "use client")
                             const insertionIndex = programNode.body.findIndex((stmt) => {

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

@@ -3,6 +3,9 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.preferUseDeepCompareMemo = void 0;
 const utils_1 = require("@typescript-eslint/utils");
 const createRule_1 = require("../utils/createRule");
+const ASTHelpers_1 = require("../utils/ASTHelpers");
+const DEEP_COMPARE_MODULE = '@blumintinc/use-deep-compare';
+const DEEP_COMPARE_HOOK = 'useDeepCompareMemo';
 // Consider these as memoizing hooks producing stable references
 const MEMOIZING_HOOKS = new Set([
     'useMemo',
@@ -154,17 +157,53 @@ function collectMemoizedIdentifiers(context) {
     visit(program);
     return memoized;
 }
+/**
+ * A specifier that binds the hook as a callable value under the exact name the
+ * rewritten call spells. An alias binds the hook to some other name, leaving
+ * `useDeepCompareMemo` unresolvable, and a type-only specifier erases at
+ * compile time, so neither can carry the call.
+ */
+function bindsDeepCompareMemo(specifier) {
+    return (specifier.type === utils_1.AST_NODE_TYPES.ImportSpecifier &&
+        specifier.importKind !== 'type' &&
+        specifier.imported.type === utils_1.AST_NODE_TYPES.Identifier &&
+        specifier.imported.name === DEEP_COMPARE_HOOK &&
+        specifier.local.name === DEEP_COMPARE_HOOK);
+}
+/**
+ * The hook's import read off `Program.body` rather than off a flag set by an
+ * ImportDeclaration visitor, so the answer holds under multi-pass `--fix`
+ * wherever the import sits relative to the fix site.
+ */
+function findDeepCompareMemoImport(program) {
+    for (const statement of program.body) {
+        if (statement.type !== utils_1.AST_NODE_TYPES.ImportDeclaration ||
+            statement.source.value !== DEEP_COMPARE_MODULE ||
+            (statement.importKind && statement.importKind !== 'value')) {
+            continue;
+        }
+        const specifier = statement.specifiers.find(bindsDeepCompareMemo);
+        if (specifier)
+            return specifier;
+    }
+    return null;
+}
+/**
+ * Whether the visible `useDeepCompareMemo` binding is the very import this fix
+ * would otherwise insert. Reusing that binding is the intended path; any other
+ * binding of the name belongs to the file's author.
+ */
+function bindsHookImport(variable, hookImport) {
+    return (hookImport !== null &&
+        variable.defs.length > 0 &&
+        variable.defs.every((def) => def.node === hookImport));
+}
 function ensureDeepCompareImportFixes(context, fixer) {
     const fixes = [];
     const sourceCode = context.sourceCode;
     const program = sourceCode.ast;
     // If already imported anywhere, skip adding
-    const hasImport = program.body.some((n) => n.type === utils_1.AST_NODE_TYPES.ImportDeclaration &&
-        n.source.value === '@blumintinc/use-deep-compare' &&
-        n.specifiers.some((s) => s.type === utils_1.AST_NODE_TYPES.ImportSpecifier &&
-            s.imported.type === utils_1.AST_NODE_TYPES.Identifier &&
-            s.imported.name === 'useDeepCompareMemo'));
-    if (hasImport)
+    if (findDeepCompareMemoImport(program))
         return fixes;
     // Determine insertion point and indentation
     const importDecls = program.body.filter((n) => n.type === utils_1.AST_NODE_TYPES.ImportDeclaration);
@@ -377,6 +416,10 @@ exports.preferUseDeepCompareMemo = (0, createRule_1.createRule)({
                 }
                 if (!hasUnmemoizedNonPrimitive)
                     return;
+                // Captured during traversal because the fix runs afterwards, when an
+                // ESLint version lacking sourceCode.getScope can only report the
+                // global scope and would miss a narrower shadow.
+                const scope = ASTHelpers_1.ASTHelpers.getScope(context, node);
                 context.report({
                     node,
                     messageId: 'preferUseDeepCompareMemo',
@@ -384,6 +427,19 @@ exports.preferUseDeepCompareMemo = (0, createRule_1.createRule)({
                         hook: 'useMemo',
                     },
                     fix(fixer) {
+                        // Resolve the emitted name through the scope chain at the call
+                        // site. A binding that is not this fix's own import makes the edit
+                        // wrong twice over: the inserted import declares the name a second
+                        // time (TS2440/TS2300), and a shadowing parameter or local silently
+                        // routes the call to the wrong value with no diagnostic at all.
+                        // Declining leaves the report so the author migrates deliberately —
+                        // including the useMemo specifier removal below, which would
+                        // otherwise strip an import the untouched call site still needs.
+                        const existing = ASTHelpers_1.ASTHelpers.findVariableInScope(scope, DEEP_COMPARE_HOOK);
+                        if (existing &&
+                            !bindsHookImport(existing, findDeepCompareMemoImport(context.sourceCode.ast))) {
+                            return null;
+                        }
                         const fixes = [];
                         // Replace callee
                         if (node.callee.type === utils_1.AST_NODE_TYPES.Identifier) {

package/lib/rules/require-dynamic-firebase-imports.d.ts

@@ -1,6 +1,6 @@
-import { TSESTree } from '@typescript-eslint/utils';
+import { TSESLint, TSESTree } from '@typescript-eslint/utils';
 export declare const RULE_NAME = "require-dynamic-firebase-imports";
-declare const _default: import("@typescript-eslint/utils/dist/ts-eslint/Rule").RuleModule<"requireDynamicImport", never[], {
+declare const _default: TSESLint.RuleModule<"requireDynamicImport", never[], {
     ImportDeclaration(node: TSESTree.ImportDeclaration): void;
 }>;
 export default _default;

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

@@ -3,7 +3,79 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.RULE_NAME = void 0;
 const utils_1 = require("@typescript-eslint/utils");
 const createRule_1 = require("../utils/createRule");
+const ASTHelpers_1 = require("../utils/ASTHelpers");
 exports.RULE_NAME = 'require-dynamic-firebase-imports';
+/**
+ * A specifier is erased at compile time when either the whole statement is an
+ * `import type` or the specifier carries an inline `type` marker. Only such a
+ * specifier is interchangeable with the `import type` the fixer hoists.
+ */
+const isErasableTypeSpecifier = (declaration, specifier) => declaration.importKind === 'type' || specifier.importKind === 'type';
+/**
+ * Whether `specifier` binds the same local name to the same export of
+ * `importSource` in type position as `target` — i.e. whether it is exactly the
+ * binding the hoisted `import type` would introduce.
+ */
+const bindsSameTypeImport = (specifier, target, importSource) => {
+    if (specifier.type !== utils_1.AST_NODE_TYPES.ImportSpecifier ||
+        specifier.local.name !== target.local.name ||
+        specifier.imported.name !== target.imported.name) {
+        return false;
+    }
+    const declaration = specifier.parent;
+    return (declaration?.type === utils_1.AST_NODE_TYPES.ImportDeclaration &&
+        declaration.source.value === importSource &&
+        isErasableTypeSpecifier(declaration, specifier));
+};
+/**
+ * Read the module-scope import state off `Program.body` rather than a traversal
+ * flag: `--fix` runs multiple passes, and a sibling report in an earlier pass may
+ * already have hoisted the same `import type`. A flag set by the
+ * `ImportDeclaration` visitor also depends on source order, so it would be stale
+ * for any import that precedes the one being rewritten.
+ */
+const findHoistedTypeImport = (program, target, importSource) => {
+    for (const statement of program.body) {
+        if (statement.type !== utils_1.AST_NODE_TYPES.ImportDeclaration) {
+            continue;
+        }
+        const match = statement.specifiers.find((specifier) => bindsSameTypeImport(specifier, target, importSource));
+        if (match) {
+            return match;
+        }
+    }
+    return undefined;
+};
+/**
+ * The binding that makes hoisting `target` unsafe, or `null` when the name is
+ * free (or already bound to the very import being hoisted).
+ *
+ * Resolution walks the scope chain of the rewritten import instead of stopping
+ * at module scope, because a narrower shadow raises no TypeScript diagnostic yet
+ * silently binds the hoisted type to the wrong declaration. Each hop resolves a
+ * single step further up: the rewritten statement binds its own inline `type`
+ * specifier in the enclosing function scope, which would otherwise mask the
+ * colliding declaration above it. Bindings without a definition are ambient
+ * (TypeScript lib types, configured globals); a module-scope import legally
+ * shadows those, so they are not collisions.
+ */
+const findCollidingBinding = (scope, target, importSource) => {
+    let current = scope;
+    while (current) {
+        const existing = ASTHelpers_1.ASTHelpers.findVariableInScope(current, target.local.name);
+        if (!existing) {
+            return null;
+        }
+        if (existing.defs.length > 0) {
+            const bindsTheDesiredImport = existing.defs.every((def) => bindsSameTypeImport(def.node, target, importSource));
+            if (!bindsTheDesiredImport) {
+                return existing;
+            }
+        }
+        current = existing.scope.upper;
+    }
+    return null;
+};
 exports.default = (0, createRule_1.createRule)({
     name: exports.RULE_NAME,
     meta: {
@@ -109,16 +181,32 @@ exports.default = (0, createRule_1.createRule)({
                         if (!isInsideAsyncFunction(node)) {
                             return null;
                         }
+                        // Type specifiers must not travel into the runtime destructuring:
+                        // they have no runtime value, and dropping the `type` marker turns
+                        // type references into dangling value bindings. They hoist into a
+                        // static `import type` at module scope, which is erased at compile
+                        // time.
+                        const scope = ASTHelpers_1.ASTHelpers.getScope(context, node);
+                        const program = context.getSourceCode().ast;
+                        const specifiersToHoist = [];
+                        for (const specifier of typeSpecifiers) {
+                            if (findCollidingBinding(scope, specifier, importSource)) {
+                                // Declining the whole fix keeps the file compiling: applying
+                                // the dynamic import while skipping a colliding hoist would
+                                // strand the type reference (TS2749) instead of duplicating an
+                                // identifier (TS2440/TS2300). The report stands so the author
+                                // resolves the name clash deliberately.
+                                return null;
+                            }
+                            if (!findHoistedTypeImport(program, specifier, importSource)) {
+                                specifiersToHoist.push(specifier);
+                            }
+                        }
                         const fixes = [
                             fixer.replaceText(node, buildDynamicImport(importSource, valueSpecifiers)),
                         ];
-                        if (typeSpecifiers.length > 0) {
-                            // Type specifiers must not travel into the runtime
-                            // destructuring: they have no runtime value, and dropping the
-                            // `type` marker turns type references into dangling value
-                            // bindings. Hoist them into a static `import type` at module
-                            // scope, which is erased at compile time.
-                            fixes.push(fixer.insertTextBeforeRange([0, 0], buildStaticTypeImport(importSource, typeSpecifiers)));
+                        if (specifiersToHoist.length > 0) {
+                            fixes.push(fixer.insertTextBeforeRange([0, 0], buildStaticTypeImport(importSource, specifiersToHoist)));
                         }
                         return fixes;
                     },

package/lib/rules/require-memoize-jsx-returners.js

@@ -3,12 +3,14 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.requireMemoizeJsxReturners = void 0;
 const utils_1 = require("@typescript-eslint/utils");
 const createRule_1 = require("../utils/createRule");
+const ASTHelpers_1 = require("../utils/ASTHelpers");
 const disableDirectives_1 = require("../utils/disableDirectives");
 const MEMOIZE_PREFERRED_MODULE = '@blumintinc/typescript-memoize';
 const MEMOIZE_MODULES = new Set([
     MEMOIZE_PREFERRED_MODULE,
     'typescript-memoize',
 ]);
+const MEMOIZE_EXPORT_NAME = 'Memoize';
 function isMemoizeDecorator(decorator, alias, namespaceAlias) {
     const expression = decorator.expression;
     const matchesAliasIdentifier = (node) => !!node && node.type === utils_1.AST_NODE_TYPES.Identifier && node.name === alias;
@@ -325,6 +327,66 @@ function functionReturnsJSX(fn, knownFunctions, cache, factoryContext) {
     cache.set(fn, returnsJSX);
     return returnsJSX;
 }
+/**
+ * A specifier that binds the memoize module's `Memoize` export — either by name
+ * (under any local alias) or through the module namespace.
+ */
+function isMemoizeSpecifier(specifier) {
+    if (specifier.type === utils_1.AST_NODE_TYPES.ImportNamespaceSpecifier) {
+        return true;
+    }
+    return (specifier.type === utils_1.AST_NODE_TYPES.ImportSpecifier &&
+        specifier.imported.type === utils_1.AST_NODE_TYPES.Identifier &&
+        specifier.imported.name === MEMOIZE_EXPORT_NAME);
+}
+/**
+ * The binding through which the emitted decorator reaches `Memoize`, read off
+ * the program body rather than a traversal flag. `eslint --fix` re-lints between
+ * passes and inserts the import above code an earlier pass already visited, so a
+ * flag set by the `ImportDeclaration` visitor is not yet accurate for a class
+ * that precedes the import in source order.
+ */
+function findMemoizeImportBinding(program) {
+    let namedAlias = null;
+    let namespaceAlias = null;
+    for (const statement of program.body) {
+        if (statement.type !== utils_1.AST_NODE_TYPES.ImportDeclaration ||
+            !MEMOIZE_MODULES.has(String(statement.source.value))) {
+            continue;
+        }
+        for (const specifier of statement.specifiers) {
+            if (specifier.type === utils_1.AST_NODE_TYPES.ImportNamespaceSpecifier) {
+                namespaceAlias = specifier.local.name;
+            }
+            else if (isMemoizeSpecifier(specifier)) {
+                namedAlias = specifier.local?.name ?? namedAlias;
+            }
+        }
+    }
+    /** `namespace.Memoize` stays valid whatever the named specifiers are. */
+    if (namespaceAlias) {
+        return { localName: namespaceAlias, isNamespace: true };
+    }
+    return namedAlias ? { localName: namedAlias, isNamespace: false } : null;
+}
+/**
+ * Whether every declaration of a visible binding is the memoize import itself.
+ * Anything else — a local declaration, a parameter, a class, a default
+ * specifier, an import of the same name from another module — means the fix
+ * cannot proceed under that name.
+ */
+function bindsMemoizeImport(variable) {
+    return (variable.defs.length > 0 &&
+        variable.defs.every((def) => {
+            const specifier = def.node;
+            if (!isMemoizeSpecifier(specifier)) {
+                return false;
+            }
+            const declaration = specifier.parent;
+            return (declaration?.type === utils_1.AST_NODE_TYPES.ImportDeclaration &&
+                MEMOIZE_MODULES.has(String(declaration.source.value)));
+        }));
+}
 function getImportFixes(fixer, sourceCode, hasMemoizeImport, scheduledImportFix) {
     const fixes = [];
     if (hasMemoizeImport || scheduledImportFix) {
@@ -381,8 +443,12 @@ exports.requireMemoizeJsxReturners = (0, createRule_1.createRule)({
         if (!isVirtualFile && !/\.tsx?$/i.test(filename)) {
             return {};
         }
-        let hasMemoizeImport = false;
-        let memoizeAlias = 'Memoize';
+        /**
+         * Aliases used to recognize an existing `@Memoize()` decorator. The fixer
+         * derives its own import state from the program body instead, so these track
+         * detection only.
+         */
+        let memoizeAlias = MEMOIZE_EXPORT_NAME;
         let memoizeNamespace = null;
         let scheduledImportFix = false;
         /**
@@ -430,13 +496,11 @@ exports.requireMemoizeJsxReturners = (0, createRule_1.createRule)({
                 for (const specifier of node.specifiers) {
                     if (specifier.type === utils_1.AST_NODE_TYPES.ImportSpecifier) {
                         if (specifier.imported.type === utils_1.AST_NODE_TYPES.Identifier &&
-                            specifier.imported.name === 'Memoize') {
-                            hasMemoizeImport = true;
+                            specifier.imported.name === MEMOIZE_EXPORT_NAME) {
                             memoizeAlias = specifier.local?.name ?? memoizeAlias;
                         }
                     }
                     else if (specifier.type === utils_1.AST_NODE_TYPES.ImportNamespaceSpecifier) {
-                        hasMemoizeImport = true;
                         memoizeNamespace = specifier.local.name;
                     }
                 }
@@ -459,9 +523,6 @@ exports.requireMemoizeJsxReturners = (0, createRule_1.createRule)({
                 if (!functionReturnsJSX(node.value, localFunctions, jsxReturnCache, factoryContext)) {
                     return;
                 }
-                const decoratorIdent = memoizeNamespace
-                    ? `${memoizeNamespace}.Memoize`
-                    : memoizeAlias;
                 // The report is emitted even when suppressed: ESLint discards it, and
                 // reporting keeps the user's disable directive "used" so that
                 // `--report-unused-disable-directives` does not flag it.
@@ -477,7 +538,24 @@ exports.requireMemoizeJsxReturners = (0, createRule_1.createRule)({
                             return null;
                         }
                         const sourceCode = context.getSourceCode();
-                        const { fixes, scheduledImportFix: newScheduledImportFix } = getImportFixes(fixer, sourceCode, hasMemoizeImport, scheduledImportFix);
+                        const memoizeImport = findMemoizeImportBinding(sourceCode.ast);
+                        const decoratorBaseName = memoizeImport?.localName ?? MEMOIZE_EXPORT_NAME;
+                        // Resolve the decorator's identifier through the scope chain at the
+                        // member being fixed. A binding that is not the memoize import
+                        // makes both halves of the edit wrong: the inserted
+                        // `import { Memoize }` collides with a top-level binding of that
+                        // name (TS2440/TS2300), and a narrower shadow silently binds
+                        // `@Memoize()` to the shadow with no TypeScript diagnostic at all.
+                        // Declining leaves the report in place so the author resolves the
+                        // conflict deliberately.
+                        const existing = ASTHelpers_1.ASTHelpers.findVariableInScope(ASTHelpers_1.ASTHelpers.getScope(context, node), decoratorBaseName);
+                        if (existing && !bindsMemoizeImport(existing)) {
+                            return null;
+                        }
+                        const decoratorIdent = memoizeImport?.isNamespace
+                            ? `${memoizeImport.localName}.${MEMOIZE_EXPORT_NAME}`
+                            : decoratorBaseName;
+                        const { fixes, scheduledImportFix: newScheduledImportFix } = getImportFixes(fixer, sourceCode, !!memoizeImport, scheduledImportFix);
                         scheduledImportFix = newScheduledImportFix;
                         const insertionTarget = node.decorators && node.decorators.length > 0
                             ? node.decorators[0]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blumintinc/eslint-plugin-blumint",
-  "version": "1.20.31",
+  "version": "1.20.32",
   "description": "Custom eslint rules for use within BluMint",
   "author": {
     "name": "Brodie McGuire",

package/release-manifest.json

@@ -1,4 +1,74 @@
 [
+  {
+    "version": "1.20.32",
+    "date": "2026-07-30T12:36:24.525Z",
+    "rules": [
+      {
+        "name": "enforce-microdiff",
+        "changeType": "fix",
+        "issues": [
+          1429
+        ],
+        "summary": "decline the fix when `diff` is already bound (closes #1429)"
+      },
+      {
+        "name": "enforce-stable-hash-spread-props",
+        "changeType": "fix",
+        "issues": [
+          1430
+        ],
+        "summary": "decline the fix when `stableHash` is already bound (closes #1430)"
+      },
+      {
+        "name": "fast-deep-equal-over-microdiff",
+        "changeType": "fix",
+        "issues": [
+          1435
+        ],
+        "summary": "decline the fix when `isEqual` is already bound (closes #1435)"
+      },
+      {
+        "name": "prefer-global-router-state-key",
+        "changeType": "fix",
+        "issues": [
+          1431
+        ],
+        "summary": "decline the fix when the derived query-key constant is already bound (closes #1431)"
+      },
+      {
+        "name": "prefer-next-dynamic",
+        "changeType": "fix",
+        "issues": [
+          1432
+        ],
+        "summary": "decline the fix when `dynamic` is already bound (closes #1432)"
+      },
+      {
+        "name": "prefer-use-deep-compare-memo",
+        "changeType": "fix",
+        "issues": [
+          1436
+        ],
+        "summary": "decline the fix when `useDeepCompareMemo` is already bound (closes #1436)"
+      },
+      {
+        "name": "require-dynamic-firebase-imports",
+        "changeType": "fix",
+        "issues": [
+          1433
+        ],
+        "summary": "decline the fix when a hoisted type name is already bound (closes #1433)"
+      },
+      {
+        "name": "require-memoize-jsx-returners",
+        "changeType": "fix",
+        "issues": [
+          1434
+        ],
+        "summary": "decline the fix when `Memoize` is already bound (closes #1434)"
+      }
+    ]
+  },
   {
     "version": "1.20.31",
     "date": "2026-07-30T11:41:49.100Z",