@blumintinc/eslint-plugin-blumint 1.20.22 → 1.20.23

package/lib/index.js

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

package/lib/rules/no-array-length-in-deps.js

@@ -97,6 +97,122 @@ function findEnclosingFunction(node) {
     }
     return null;
 }
+/**
+ * The memo declaration must land immediately before the statement containing
+ * the hook call, inside the innermost enclosing block. Module scope is never
+ * a valid target: useMemo is only legal inside a component/hook, and the
+ * tracked array is typically function-local, so a top-level insertion would
+ * reference an unbound variable and violate the rules of hooks.
+ */
+function findInsertionPoint(node) {
+    const enclosingFunction = findEnclosingFunction(node);
+    if (!enclosingFunction)
+        return null;
+    let current = node;
+    while (current.parent) {
+        // Reaching the function before any block means an expression-bodied
+        // arrow: there is no statement position to hold the declaration.
+        if (current === enclosingFunction)
+            return null;
+        const parent = current.parent;
+        if (parent.type === utils_1.AST_NODE_TYPES.BlockStatement) {
+            return { statement: current, block: parent };
+        }
+        current = parent;
+    }
+    return null;
+}
+/**
+ * Collects the identifiers a hoisted `stableHash(<base>)` expression would
+ * read: the root object of the member chain plus any computed keys. Property
+ * names are not variable references. Returns false for shapes that cannot be
+ * hoisted verbatim (this-expressions, calls, casts) so the fixer bails.
+ */
+function collectBaseReferences(expr, out) {
+    switch (expr.type) {
+        case utils_1.AST_NODE_TYPES.Identifier:
+            out.push(expr);
+            return true;
+        case utils_1.AST_NODE_TYPES.MemberExpression:
+            if (!collectBaseReferences(expr.object, out))
+                return false;
+            if (expr.computed)
+                return collectBaseReferences(expr.property, out);
+            return true;
+        case utils_1.AST_NODE_TYPES.ChainExpression:
+            return collectBaseReferences(expr.expression, out);
+        case utils_1.AST_NODE_TYPES.TSNonNullExpression:
+            return collectBaseReferences(expr.expression, out);
+        case utils_1.AST_NODE_TYPES.Literal:
+            return true;
+        default:
+            return false;
+    }
+}
+/**
+ * A base is safe to memoize at the insertion point only when every variable
+ * it reads is provably bound there: declared in a scope that encloses the
+ * insertion block, and (for lexical declarations) positioned before the
+ * consuming statement so the hoisted read cannot hit the temporal dead zone.
+ * Unresolvable or ambient names are rejected — a report without a fix is
+ * always preferable to generated code that references an unbound variable.
+ */
+function isBaseSafeToHoist(context, baseExpr, insertion) {
+    const identifiers = [];
+    if (!collectBaseReferences(baseExpr, identifiers))
+        return false;
+    if (identifiers.length === 0)
+        return false;
+    for (const identifier of identifiers) {
+        const scope = ASTHelpers_1.ASTHelpers.getScope(context, identifier);
+        const variable = ASTHelpers_1.ASTHelpers.findVariableInScope(scope, identifier.name);
+        if (!variable || variable.defs.length === 0)
+            return false;
+        // Visibility: the variable's scope must enclose the insertion block.
+        // Because the insertion point shares the hook's scope chain, an enclosing
+        // scope here guarantees the same binding resolves at both positions.
+        const scopeBlock = variable.scope.block;
+        if (!rangeContains(scopeBlock, insertion.block))
+            return false;
+        for (const def of variable.defs) {
+            if (def.type === 'Parameter' || def.type === 'ImportBinding')
+                continue;
+            if (def.type === 'FunctionName' &&
+                def.node.type === utils_1.AST_NODE_TYPES.FunctionDeclaration) {
+                continue;
+            }
+            // Lexical declarations must precede the insertion point textually.
+            if (def.name.range[1] > insertion.statement.range[0])
+                return false;
+        }
+    }
+    return true;
+}
+/**
+ * An `eslint-disable-next-line` comment directly above the hook statement
+ * targets the hook, so the memo declaration must go above the comment —
+ * inserting between them would silently re-point the suppression at the memo.
+ */
+function findDeclarationAnchor(sourceCode, statement) {
+    let anchor = statement;
+    const comments = sourceCode.getCommentsBefore(statement);
+    for (let i = comments.length - 1; i >= 0; i--) {
+        const comment = comments[i];
+        if (comment.loc.end.line === anchor.loc.start.line - 1 &&
+            /^\s*eslint-disable-next-line\b/.test(comment.value)) {
+            anchor = comment;
+        }
+        else {
+            break;
+        }
+    }
+    return anchor;
+}
+function getAnchorIndent(sourceCode, anchor) {
+    const line = sourceCode.lines[anchor.loc.start.line - 1] ?? '';
+    const prefix = line.slice(0, anchor.loc.start.column);
+    return /^\s*$/.test(prefix) ? prefix : '';
+}
 function ensureWeakMapEntry(map, key, factory) {
     const existing = map.get(key);
     if (existing)
@@ -105,22 +221,48 @@ function ensureWeakMapEntry(map, key, factory) {
     map.set(key, next);
     return next;
 }
-function isUseMemoImported(sourceCode) {
-    const program = sourceCode.ast;
-    for (const node of program.body) {
-        if (node.type === utils_1.AST_NODE_TYPES.ImportDeclaration &&
-            node.source.value === 'react') {
-            for (const spec of node.specifiers) {
-                if (spec.type === utils_1.AST_NODE_TYPES.ImportSpecifier &&
-                    spec.imported.type === utils_1.AST_NODE_TYPES.Identifier &&
-                    spec.imported.name === 'useMemo') {
-                    return true;
-                }
+function getValueImports(sourceCode, source) {
+    return sourceCode.ast.body.filter((node) => node.type === utils_1.AST_NODE_TYPES.ImportDeclaration &&
+        node.source.value === source &&
+        node.importKind !== 'type');
+}
+/**
+ * The generated code calls the helper by its canonical name, so an aliased
+ * specifier (`useMemo as um`) or a type-only specifier does not count — the
+ * value binding under the exact local name must exist.
+ */
+function hasNamedValueImport(sourceCode, source, name) {
+    for (const declaration of getValueImports(sourceCode, source)) {
+        for (const spec of declaration.specifiers) {
+            if (spec.type === utils_1.AST_NODE_TYPES.ImportSpecifier &&
+                spec.importKind !== 'type' &&
+                spec.imported.type === utils_1.AST_NODE_TYPES.Identifier &&
+                spec.imported.name === name &&
+                spec.local.name === name) {
+                return true;
             }
         }
     }
     return false;
 }
+/**
+ * Extends an existing import from `source` with `name` instead of prepending
+ * a duplicate declaration. Namespace-only imports cannot host a named
+ * specifier, so those fall through to a separate declaration (null).
+ */
+function buildImportExtensionFix(fixer, sourceCode, source, name) {
+    for (const declaration of getValueImports(sourceCode, source)) {
+        const named = declaration.specifiers.filter((spec) => spec.type === utils_1.AST_NODE_TYPES.ImportSpecifier);
+        if (named.length > 0) {
+            return fixer.insertTextAfter(named[named.length - 1], `, ${name}`);
+        }
+        const defaultSpec = declaration.specifiers.find((spec) => spec.type === utils_1.AST_NODE_TYPES.ImportDefaultSpecifier);
+        if (defaultSpec) {
+            return fixer.insertTextAfter(defaultSpec, `, { ${name} }`);
+        }
+    }
+    return null;
+}
 /**
  * Hook callback = first function-typed argument (the effect/factory/memo fn).
  * Deps array is the LAST argument; the callback precedes it.
@@ -184,22 +326,6 @@ function isLengthOnlyUsage(context, callback, baseExpr) {
     }
     return bodyReferences.every((ref) => isLengthAccessOf(ref.identifier));
 }
-function isStableHashImported(sourceCode, hashSource, hashImportName) {
-    const program = sourceCode.ast;
-    for (const node of program.body) {
-        if (node.type === utils_1.AST_NODE_TYPES.ImportDeclaration &&
-            node.source.value === hashSource) {
-            for (const spec of node.specifiers) {
-                if (spec.type === utils_1.AST_NODE_TYPES.ImportSpecifier &&
-                    spec.imported.type === utils_1.AST_NODE_TYPES.Identifier &&
-                    spec.imported.name === hashImportName) {
-                    return true;
-                }
-            }
-        }
-    }
-    return false;
-}
 exports.noArrayLengthInDeps = (0, createRule_1.createRule)({
     name: 'no-array-length-in-deps',
     meta: {
@@ -237,10 +363,13 @@ exports.noArrayLengthInDeps = (0, createRule_1.createRule)({
             source: hashImport?.source ?? DEFAULT_HASH_IMPORT.source,
             importName: hashImport?.importName ?? DEFAULT_HASH_IMPORT.importName,
         };
-        // Track planned file-wide changes to avoid overlapping fixers
+        // Track planned file-wide changes to avoid overlapping fixers. Bases are
+        // deduplicated per insertion block: a memo declared in one block is not
+        // visible in a sibling block, so sharing across a whole function would
+        // strand references.
         let importsPlanned = false;
-        const perFuncDeclaredBases = new WeakMap();
-        const perFuncBaseToVar = new WeakMap();
+        const perBlockDeclaredBases = new WeakMap();
+        const perBlockBaseToVar = new WeakMap();
         return {
             CallExpression(node) {
                 if (!isHookCall(node))
@@ -283,10 +412,20 @@ exports.noArrayLengthInDeps = (0, createRule_1.createRule)({
                         dependencies,
                     },
                     fix(fixer) {
+                        // All bail checks precede any shared-state mutation so a skipped
+                        // fix cannot make a later fix believe imports or declarations are
+                        // already handled.
+                        const insertion = findInsertionPoint(node);
+                        if (!insertion)
+                            return null;
+                        for (const { member } of lengthDeps) {
+                            if (!isBaseSafeToHoist(context, getBaseExpression(member), insertion)) {
+                                return null;
+                            }
+                        }
                         const fixes = [];
-                        const hostFn = findEnclosingFunction(node) ?? sourceCode.ast;
-                        const declaredBases = ensureWeakMapEntry(perFuncDeclaredBases, hostFn, () => new Set());
-                        const baseToVar = ensureWeakMapEntry(perFuncBaseToVar, hostFn, () => new Map());
+                        const declaredBases = ensureWeakMapEntry(perBlockDeclaredBases, insertion.block, () => new Set());
+                        const baseToVar = ensureWeakMapEntry(perBlockBaseToVar, insertion.block, () => new Map());
                         // Prepare variable names (consistent across file) and taken names (across all scopes)
                         const allTaken = collectAllTakenNames(sourceCode);
                         for (const name of baseToVar.values()) {
@@ -302,71 +441,52 @@ exports.noArrayLengthInDeps = (0, createRule_1.createRule)({
                                 allTaken.add(varName);
                             }
                         }
-                        // Build declarations text (one per base)
+                        // Build declaration lines (one per base) that land immediately
+                        // before the statement consuming the hook, inside the same block
+                        // as the tracked variable.
+                        const anchor = findDeclarationAnchor(sourceCode, insertion.statement);
+                        const indent = getAnchorIndent(sourceCode, anchor);
                         let declText = '';
                         for (const { member } of lengthDeps) {
                             const baseExpr = getBaseExpression(member);
                             const baseText = sourceCode.getText(baseExpr);
                             if (!declaredBases.has(baseText)) {
                                 const varName = baseToVar.get(baseText);
-                                declText += `const ${varName} = useMemo(() => ${hashImportConfig.importName}(${baseText}), [${baseText}]);\n`;
+                                declText += `const ${varName} = useMemo(() => ${hashImportConfig.importName}(${baseText}), [${baseText}]);\n${indent}`;
                                 declaredBases.add(baseText);
                             }
                         }
                         if (declText) {
-                            // Add a blank line after declarations block
-                            declText += `\n`;
+                            fixes.push(fixer.insertTextBeforeRange(anchor.range, declText));
                         }
-                        // Determine import text and insertion strategy
-                        const program = sourceCode.ast;
-                        const importDecls = program.body.filter((n) => n.type === utils_1.AST_NODE_TYPES.ImportDeclaration);
-                        // Compute indentation based on the whitespace before the first token
-                        const fullText = sourceCode.getText();
-                        const prefixBeforeProgram = fullText.slice(0, program.range[0]);
-                        const lastNewlineIndex = prefixBeforeProgram.lastIndexOf('\n');
-                        const indent = lastNewlineIndex >= 0
-                            ? prefixBeforeProgram.slice(lastNewlineIndex + 1)
-                            : prefixBeforeProgram;
-                        let importText = '';
-                        const needUseMemo = !isUseMemoImported(sourceCode);
-                        const needStableHash = !isStableHashImported(sourceCode, hashImportConfig.source, hashImportConfig.importName);
-                        if (needUseMemo)
-                            importText += `${indent}import { useMemo } from 'react';\n`;
-                        if (needStableHash)
-                            importText += `${indent}import { ${hashImportConfig.importName} } from '${hashImportConfig.source}';\n`;
-                        if (importDecls.length === 0) {
-                            // No existing imports. Normalize by removing leading whitespace and inserting at file start with no indentation.
-                            if (declText || importText) {
-                                // Build non-indented versions of import and decl blocks
-                                let importTextNoIndent = '';
-                                if (needUseMemo)
-                                    importTextNoIndent += `import { useMemo } from 'react';\n`;
-                                if (needStableHash)
-                                    importTextNoIndent += `import { ${hashImportConfig.importName} } from '${hashImportConfig.source}';\n`;
-                                const declNoIndent = declText;
-                                const combined = `${importTextNoIndent}${importTextNoIndent && declNoIndent ? '\n' : ''}${declNoIndent}`;
-                                // Remove leading whitespace
-                                fixes.push(fixer.replaceTextRange([0, program.range[0]], ''));
-                                // Insert at column 0
-                                fixes.push(fixer.insertTextBeforeRange([0, 0], combined));
+                        if (!importsPlanned) {
+                            const newImportLines = [];
+                            if (!hasNamedValueImport(sourceCode, 'react', 'useMemo')) {
+                                const extension = buildImportExtensionFix(fixer, sourceCode, 'react', 'useMemo');
+                                if (extension)
+                                    fixes.push(extension);
+                                else
+                                    newImportLines.push(`import { useMemo } from 'react';`);
                             }
-                            importsPlanned = true;
-                        }
-                        else {
-                            // Existing imports present: insert missing import lines before the first import, and declarations after the last import
-                            const firstImport = importDecls[0];
-                            const lastImport = importDecls[importDecls.length - 1];
-                            if (importText && !importsPlanned) {
-                                fixes.push(fixer.insertTextBefore(firstImport, importText));
-                                importsPlanned = true;
+                            if (!hasNamedValueImport(sourceCode, hashImportConfig.source, hashImportConfig.importName)) {
+                                const extension = buildImportExtensionFix(fixer, sourceCode, hashImportConfig.source, hashImportConfig.importName);
+                                if (extension)
+                                    fixes.push(extension);
+                                else {
+                                    newImportLines.push(`import { ${hashImportConfig.importName} } from '${hashImportConfig.source}';`);
+                                }
                             }
-                            if (declText) {
-                                const declWithIndent = declText
-                                    .split('\n')
-                                    .map((line) => (line ? `${indent}${line}` : line))
-                                    .join('\n');
-                                fixes.push(fixer.insertTextAfter(lastImport, `\n${declWithIndent}`));
+                            if (newImportLines.length > 0) {
+                                const importText = `${newImportLines.join('\n')}\n`;
+                                const firstImport = sourceCode.ast.body.find((n) => n.type === utils_1.AST_NODE_TYPES.ImportDeclaration);
+                                if (firstImport) {
+                                    fixes.push(fixer.insertTextBefore(firstImport, importText));
+                                }
+                                else {
+                                    fixes.push(fixer.insertTextBeforeRange([0, 0], importText));
+                                }
                             }
+                            importsPlanned = true;
                         }
                         // Replace each .length dep with the corresponding var name
                         for (const { element, member } of lengthDeps) {

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

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.RULE_NAME = void 0;
+const utils_1 = require("@typescript-eslint/utils");
 const createRule_1 = require("../utils/createRule");
 exports.RULE_NAME = 'require-dynamic-firebase-imports';
 exports.default = (0, createRule_1.createRule)({
@@ -23,62 +24,105 @@ exports.default = (0, createRule_1.createRule)({
             return (source.startsWith('firebase/') ||
                 source.includes('config/firebase-client'));
         };
-        const createDynamicImport = (node) => {
-            const importSource = node.source.value;
-            const importSpecifiers = node.specifiers;
-            if (importSpecifiers.length === 0) {
-                // For side-effect imports like 'firebase/auth'
+        /**
+         * `await import()` is only valid inside an async function. Rewriting a
+         * module-scope import would introduce top-level await, silently converting
+         * a synchronous module into an async one (and failing outright on build
+         * targets without top-level await support) — so those sites are reported
+         * without a fix.
+         */
+        const isInsideAsyncFunction = (node) => {
+            let current = node.parent;
+            while (current) {
+                if (current.type === utils_1.AST_NODE_TYPES.FunctionDeclaration ||
+                    current.type === utils_1.AST_NODE_TYPES.FunctionExpression ||
+                    current.type === utils_1.AST_NODE_TYPES.ArrowFunctionExpression) {
+                    // The nearest enclosing function decides await validity; an async
+                    // ancestor beyond a sync function cannot host the await.
+                    return current.async;
+                }
+                current = current.parent;
+            }
+            return false;
+        };
+        const isTypeOnlySpecifier = (spec) => spec.type === utils_1.AST_NODE_TYPES.ImportSpecifier &&
+            spec.importKind === 'type';
+        const buildDynamicImport = (importSource, valueSpecifiers) => {
+            if (valueSpecifiers.length === 0) {
+                // Side-effect imports have no bindings to destructure.
                 return `await import('${importSource}');`;
             }
-            if (importSpecifiers.length === 1) {
-                const spec = importSpecifiers[0];
-                if (spec.type === 'ImportDefaultSpecifier') {
-                    // For default imports
-                    return `const ${spec.local.name} = (await import('${importSource}')).default;`;
-                }
-                if (spec.type === 'ImportSpecifier') {
-                    // For single named import
-                    const importedName = spec.imported.name;
-                    const localName = spec.local.name;
-                    if (importedName === localName) {
-                        return `const { ${localName} } = await import('${importSource}');`;
-                    }
-                    return `const { ${importedName}: ${localName} } = await import('${importSource}');`;
+            const namespaceSpecifier = valueSpecifiers.find((spec) => spec.type === utils_1.AST_NODE_TYPES.ImportNamespaceSpecifier);
+            const defaultSpecifier = valueSpecifiers.find((spec) => spec.type === utils_1.AST_NODE_TYPES.ImportDefaultSpecifier);
+            const namedSpecifiers = valueSpecifiers.filter((spec) => spec.type === utils_1.AST_NODE_TYPES.ImportSpecifier);
+            if (namespaceSpecifier) {
+                // The promise resolved by `import()` IS the module namespace object,
+                // so the `* as ns` binding maps directly onto it.
+                const namespaceDeclaration = `const ${namespaceSpecifier.local.name} = await import('${importSource}');`;
+                if (defaultSpecifier) {
+                    return `${namespaceDeclaration} const ${defaultSpecifier.local.name} = ${namespaceSpecifier.local.name}.default;`;
                 }
+                return namespaceDeclaration;
             }
-            // For multiple named imports
-            const importedModule = `await import('${importSource}')`;
-            const namedImports = importSpecifiers
-                .map((spec) => {
-                if (spec.type === 'ImportSpecifier') {
-                    const importedName = spec.imported.name;
-                    const localName = spec.local.name;
-                    return importedName === localName
-                        ? localName
-                        : `${importedName}: ${localName}`;
+            const destructuredNames = namedSpecifiers.map((spec) => spec.imported.name === spec.local.name
+                ? spec.local.name
+                : `${spec.imported.name}: ${spec.local.name}`);
+            if (defaultSpecifier) {
+                if (destructuredNames.length === 0) {
+                    return `const ${defaultSpecifier.local.name} = (await import('${importSource}')).default;`;
                 }
-                return '';
-            })
-                .filter(Boolean)
-                .join(', ');
-            return `const { ${namedImports} } = ${importedModule};`;
+                // The namespace object exposes the default export under `default`.
+                return `const { default: ${defaultSpecifier.local.name}, ${destructuredNames.join(', ')} } = await import('${importSource}');`;
+            }
+            return `const { ${destructuredNames.join(', ')} } = await import('${importSource}');`;
+        };
+        const buildStaticTypeImport = (importSource, typeSpecifiers) => {
+            const names = typeSpecifiers.map((spec) => spec.imported.name === spec.local.name
+                ? spec.local.name
+                : `${spec.imported.name} as ${spec.local.name}`);
+            return `import type { ${names.join(', ')} } from '${importSource}';\n`;
         };
         return {
             ImportDeclaration(node) {
                 const importSource = node.source.value;
-                if (typeof importSource === 'string' &&
-                    isFirebaseImport(importSource) &&
-                    !node.importKind?.includes('type')) {
-                    context.report({
-                        node,
-                        messageId: 'requireDynamicImport',
-                        data: { importSource },
-                        fix(fixer) {
-                            const dynamicImport = createDynamicImport(node);
-                            return fixer.replaceText(node, dynamicImport);
-                        },
-                    });
+                if (typeof importSource !== 'string' ||
+                    !isFirebaseImport(importSource)) {
+                    return;
+                }
+                // `import type` statements are erased at compile time, so they add no
+                // bundle weight — and a dynamic import cannot supply types anyway.
+                if (node.importKind === 'type') {
+                    return;
+                }
+                const typeSpecifiers = node.specifiers.filter(isTypeOnlySpecifier);
+                const valueSpecifiers = node.specifiers.filter((spec) => !isTypeOnlySpecifier(spec));
+                // Inline `type` markers on every specifier make the whole statement
+                // erasable, exactly like `import type` — nothing to report.
+                if (node.specifiers.length > 0 && valueSpecifiers.length === 0) {
+                    return;
                 }
+                context.report({
+                    node,
+                    messageId: 'requireDynamicImport',
+                    data: { importSource },
+                    fix(fixer) {
+                        if (!isInsideAsyncFunction(node)) {
+                            return null;
+                        }
+                        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)));
+                        }
+                        return fixes;
+                    },
+                });
             },
         };
     },

package/package.json

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

package/release-manifest.json

@@ -1,4 +1,26 @@
 [
+  {
+    "version": "1.20.23",
+    "date": "2026-07-30T01:37:58.854Z",
+    "rules": [
+      {
+        "name": "no-array-length-in-deps",
+        "changeType": "fix",
+        "issues": [
+          1398
+        ],
+        "summary": "insert generated memo in the variable's own scope (closes #1398)"
+      },
+      {
+        "name": "require-dynamic-firebase-imports",
+        "changeType": "fix",
+        "issues": [
+          1399
+        ],
+        "summary": "keep type-only specifiers out of the runtime import (closes #1399)"
+      }
+    ]
+  },
   {
     "version": "1.20.22",
     "date": "2026-07-30T00:39:18.760Z",