@blumintinc/eslint-plugin-blumint 1.20.28 → 1.20.30

package/lib/index.js

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

package/lib/rules/enforce-safe-stringify.js

@@ -3,6 +3,47 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.enforceStableStringify = void 0;
 const utils_1 = require("@typescript-eslint/utils");
 const createRule_1 = require("../utils/createRule");
+const ASTHelpers_1 = require("../utils/ASTHelpers");
+const STRINGIFY_MODULE = 'safe-stable-stringify';
+const STRINGIFY_NAME = 'stringify';
+/**
+ * A default or named specifier whose local name is `stringify` — the two shapes
+ * that make a bare `stringify` call resolve to the module's function.
+ */
+function isStringifySpecifier(specifier) {
+    return ((specifier.type === utils_1.AST_NODE_TYPES.ImportDefaultSpecifier ||
+        specifier.type === utils_1.AST_NODE_TYPES.ImportSpecifier) &&
+        specifier.local.name === STRINGIFY_NAME);
+}
+/**
+ * Read the import off the AST instead of a traversal flag: suggestions are
+ * computed per call site, and a `JSON.stringify` that precedes the import
+ * declaration in source order would otherwise be judged against a flag that the
+ * `ImportDeclaration` visitor has not set yet, duplicating the import.
+ */
+function importsStringify(program) {
+    return program.body.some((statement) => statement.type === utils_1.AST_NODE_TYPES.ImportDeclaration &&
+        statement.source.value === STRINGIFY_MODULE &&
+        statement.specifiers.some(isStringifySpecifier));
+}
+/**
+ * Whether every declaration of a visible `stringify` binding is the
+ * safe-stable-stringify import itself. A namespace import, an import from any
+ * other module, a parameter, or a local declaration all mean the replacement
+ * text would resolve somewhere other than the intended function.
+ */
+function bindsSafeStringify(variable) {
+    return (variable.defs.length > 0 &&
+        variable.defs.every((def) => {
+            const specifier = def.node;
+            if (!isStringifySpecifier(specifier)) {
+                return false;
+            }
+            const declaration = specifier.parent;
+            return (declaration?.type === utils_1.AST_NODE_TYPES.ImportDeclaration &&
+                declaration.source.value === STRINGIFY_MODULE);
+        }));
+}
 exports.enforceStableStringify = (0, createRule_1.createRule)({
     name: 'enforce-safe-stringify',
     meta: {
@@ -27,15 +68,7 @@ exports.enforceStableStringify = (0, createRule_1.createRule)({
     },
     defaultOptions: [],
     create(context) {
-        let hasStringifyImport = false;
         return {
-            ImportDeclaration(node) {
-                if (node.source.value === 'safe-stable-stringify' &&
-                    node.specifiers.some((specifier) => specifier.type === utils_1.AST_NODE_TYPES.ImportDefaultSpecifier &&
-                        specifier.local.name === 'stringify')) {
-                    hasStringifyImport = true;
-                }
-            },
             MemberExpression(node) {
                 if (node.object.type === utils_1.AST_NODE_TYPES.Identifier &&
                     node.object.name === 'JSON' &&
@@ -48,27 +81,32 @@ exports.enforceStableStringify = (0, createRule_1.createRule)({
                             {
                                 messageId: 'replaceWithStringify',
                                 fix(fixer) {
+                                    // Resolve `stringify` through the scope chain at the call
+                                    // site. A binding that is not the safe-stable-stringify
+                                    // import makes both halves of the edit wrong: the inserted
+                                    // import collides with it (TS2440/TS2300), and — for a
+                                    // shadowing parameter or local — the bare `stringify`
+                                    // replacement silently calls the shadow with no compile
+                                    // error at all. Declining leaves the report in place so the
+                                    // author migrates the call deliberately.
+                                    const existing = ASTHelpers_1.ASTHelpers.findVariableInScope(ASTHelpers_1.ASTHelpers.getScope(context, node), STRINGIFY_NAME);
+                                    if (existing && !bindsSafeStringify(existing)) {
+                                        return null;
+                                    }
                                     const fixes = [];
-                                    // Add the import only when the file lacks it. Unlike the old
-                                    // batch auto-fix, suggestions are applied one at a time with a
-                                    // re-lint in between, so we must NOT flip a shared flag here:
-                                    // each suggestion is computed independently against the
-                                    // current file, and adding the import whenever it is absent
-                                    // keeps every single-suggestion application self-contained
-                                    // (the re-lint suppresses a duplicate for later call sites).
-                                    if (!hasStringifyImport) {
-                                        const program = context.sourceCode.ast;
-                                        const firstImport = program.body.find((node) => node.type === utils_1.AST_NODE_TYPES.ImportDeclaration);
+                                    const program = context.sourceCode.ast;
+                                    // Add the import only when the file lacks it. Suggestions are
+                                    // applied one at a time with a re-lint in between, so each is
+                                    // computed independently against the current file; adding the
+                                    // import whenever it is absent keeps every single-suggestion
+                                    // application self-contained (the re-lint suppresses a
+                                    // duplicate for later call sites).
+                                    if (!importsStringify(program)) {
+                                        const firstImport = program.body.find((statement) => statement.type === utils_1.AST_NODE_TYPES.ImportDeclaration);
                                         const importStatement = "import stringify from 'safe-stable-stringify';\n";
-                                        if (firstImport) {
-                                            fixes.push(fixer.insertTextBefore(firstImport, importStatement));
-                                        }
-                                        else {
-                                            fixes.push(fixer.insertTextBefore(program.body[0], importStatement));
-                                        }
+                                        fixes.push(fixer.insertTextBefore(firstImport ?? program.body[0], importStatement));
                                     }
-                                    // Replace JSON.stringify with stringify
-                                    fixes.push(fixer.replaceText(node, 'stringify'));
+                                    fixes.push(fixer.replaceText(node, STRINGIFY_NAME));
                                     return fixes;
                                 },
                             },

package/lib/rules/global-const-style.js

@@ -83,6 +83,11 @@ const renameWouldCollide = (variable, newName) => {
     }
     return false;
 };
+// `undefined`, `NaN` and `Infinity` parse as identifiers but denote primitive
+// values rather than a binding being aliased, so they stay subject to the
+// naming check exactly like the literals they stand in for. Every other bare
+// identifier initializer is an alias (see `isBindingAlias`).
+const PRIMITIVE_VALUE_GLOBALS = new Set(['undefined', 'NaN', 'Infinity']);
 // Next.js recognizes these export names by their literal identifier, so
 // renaming them to UPPER_SNAKE_CASE silently breaks the framework contract
 // (e.g. `export const config` controls the API-route body parser / runtime).
@@ -139,6 +144,26 @@ exports.default = (0, createRule_1.createRule)({
             }
             return false;
         };
+        /**
+         * A bare identifier initializer (`export const toUsernameSlugStamp =
+         * toKvStamp;`) aliases an existing binding instead of declaring a
+         * configuration value, so the rule's premise does not hold: the alias
+         * inherits whatever convention its target follows, and a callable — the
+         * dominant case, since aliasing a re-exported function is the idiom — is
+         * always camelCase. Renaming one is also destructive, because the point of
+         * such a re-export is preserving a name importers depend on and a
+         * single-file fixer cannot rewrite them (Issue #1418).
+         *
+         * The check unwraps assertions so a type-pinned alias (`x as Foo`,
+         * `x as const`) is treated the same as the bare form. A `MemberExpression`
+         * (`Foo.bar`) is deliberately not covered — it keeps whatever behavior
+         * `isDynamicValue` already gives it.
+         */
+        const isBindingAlias = (node) => {
+            const target = unwrapAssertions(node);
+            return (target.type === utils_1.AST_NODE_TYPES.Identifier &&
+                !PRIMITIVE_VALUE_GLOBALS.has(target.name));
+        };
         const describeValueKind = (node) => {
             const target = unwrapAssertions(node);
             if (target.type === utils_1.AST_NODE_TYPES.ArrayExpression) {
@@ -209,8 +234,9 @@ exports.default = (0, createRule_1.createRule)({
                     }
                     const { name } = declaration.id;
                     const init = declaration.init;
-                    // Skip if no initializer or if it's a dynamic value or class instance
-                    if (!init || isDynamicValue(init)) {
+                    // Skip if no initializer, if it's a dynamic value or class instance,
+                    // or if it merely aliases another binding
+                    if (!init || isDynamicValue(init) || isBindingAlias(init)) {
                         return;
                     }
                     const sourceCode = context.sourceCode;

package/lib/rules/prefer-document-flattening.js

@@ -3,6 +3,11 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.preferDocumentFlattening = void 0;
 const utils_1 = require("@typescript-eslint/utils");
 const createRule_1 = require("../utils/createRule");
+const SHOULD_FLATTEN_PROPERTY = 'shouldFlatten: true';
+const SHOULD_FLATTEN_OPTIONS = `{ ${SHOULD_FLATTEN_PROPERTY} }`;
+function isPunctuator(token, value) {
+    return token.type === utils_1.AST_TOKEN_TYPES.Punctuator && token.value === value;
+}
 function isIdentifier(node) {
     return node.type === utils_1.AST_NODE_TYPES.Identifier;
 }
@@ -15,6 +20,28 @@ function isObjectExpression(node) {
 function isProperty(node) {
     return node.type === utils_1.AST_NODE_TYPES.Property;
 }
+/**
+ * Appends an entry to a comma-separated list by anchoring on its last element
+ * and deriving the separator from whatever already follows that element.
+ * Prettier formats multiline lists with a trailing comma, so prefixing a comma
+ * unconditionally yields `, ,` and a file that no longer parses. Shapes that
+ * end in neither a comma nor the expected closing punctuator are declined so a
+ * withheld suggestion is the worst outcome.
+ */
+function appendAfterLastEntry(fixer, sourceCode, lastEntry, closer, text) {
+    const nextToken = sourceCode.getTokenAfter(lastEntry);
+    if (!nextToken) {
+        return null;
+    }
+    // Inserting after an existing trailing comma reuses it as the separator.
+    if (isPunctuator(nextToken, ',')) {
+        return fixer.insertTextAfter(nextToken, ` ${text}`);
+    }
+    if (isPunctuator(nextToken, closer)) {
+        return fixer.insertTextAfter(lastEntry, `, ${text}`);
+    }
+    return null;
+}
 /**
  * Recursively checks if an object has deeply nested objects
  */
@@ -69,28 +96,45 @@ exports.preferDocumentFlattening = (0, createRule_1.createRule)({
         const docSetterInstances = [];
         // Track which DocSetter instances are used to set nested objects
         const docSetterWithNestedObjects = new Set();
-        const buildSuggestion = (instance) => {
-            const newExpr = instance.node;
-            const hasOptionsArg = newExpr.arguments.length >= 2;
-            const optionsArg = hasOptionsArg ? newExpr.arguments[1] : undefined;
-            if (optionsArg && isObjectExpression(optionsArg)) {
-                const insertPos = (optionsArg.range?.[1] ?? optionsArg.parent?.range?.[1] ?? 0) - 1;
-                const prefix = optionsArg.properties.length ? ', ' : '';
-                return [
-                    {
-                        messageId: 'addShouldFlatten',
-                        fix(fixer) {
-                            return fixer.insertTextBeforeRange([insertPos, insertPos], `${prefix}shouldFlatten: true`);
-                        },
-                    },
-                ];
+        const buildShouldFlattenFix = (fixer, newExpr) => {
+            const sourceCode = context.getSourceCode();
+            const optionsArg = newExpr.arguments.length >= 2 ? newExpr.arguments[1] : undefined;
+            if (optionsArg) {
+                // Options built elsewhere (a reference, a call, a spread) cannot gain a
+                // property through a textual edit at the call site.
+                if (!isObjectExpression(optionsArg)) {
+                    return null;
+                }
+                const lastEntry = optionsArg.properties[optionsArg.properties.length - 1];
+                if (!lastEntry) {
+                    // An empty object offers no entry to anchor on, so the opening brace
+                    // is the anchor; inserting after it preserves any enclosed comment.
+                    const openBrace = sourceCode.getFirstToken(optionsArg);
+                    if (!openBrace || !isPunctuator(openBrace, '{')) {
+                        return null;
+                    }
+                    return fixer.insertTextAfter(openBrace, ` ${SHOULD_FLATTEN_PROPERTY} `);
+                }
+                // A spread element is not a Property, yet it anchors the insertion the
+                // same way because only its end position and the token after it matter.
+                return appendAfterLastEntry(fixer, sourceCode, lastEntry, '}', SHOULD_FLATTEN_PROPERTY);
             }
-            const endPos = (newExpr.range?.[1] ?? newExpr.parent?.range?.[1] ?? 0) - 1;
+            const lastArgument = newExpr.arguments[newExpr.arguments.length - 1];
+            // With no arguments, or with spread arguments, the position the options
+            // object belongs in is unknowable.
+            if (!lastArgument || lastArgument.type === utils_1.AST_NODE_TYPES.SpreadElement) {
+                return null;
+            }
+            return appendAfterLastEntry(fixer, sourceCode, lastArgument, ')', SHOULD_FLATTEN_OPTIONS);
+        };
+        const buildSuggestion = (instance) => {
+            // ESLint drops a suggestion whose fix resolves to null, so the violation
+            // is still reported when no edit can be made confidently.
             return [
                 {
                     messageId: 'addShouldFlatten',
                     fix(fixer) {
-                        return fixer.insertTextBeforeRange([endPos, endPos], `${hasOptionsArg ? '' : ','} { shouldFlatten: true }`);
+                        return buildShouldFlattenFix(fixer, instance.node);
                     },
                 },
             ];

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

@@ -103,6 +103,7 @@ const COMPARISON_OPERATORS = new Set([
 ]);
 const MEMOIZATION_DEPS_TODO_PLACEHOLDER = '__TODO_MEMOIZATION_DEPENDENCIES__';
 const TODO_DEPS_COMMENT = `/* ${MEMOIZATION_DEPS_TODO_PLACEHOLDER} */`;
+const REACT_MODULE = 'react';
 const PARENTHESIZED_EXPRESSION_TYPE = utils_1.AST_NODE_TYPES.ParenthesizedExpression ??
     'ParenthesizedExpression';
 /**
@@ -617,32 +618,105 @@ function isReturnValueFromHook(node, owner) {
     const owningFunction = findOwningFunction(node.parent);
     return owningFunction === owner;
 }
+/**
+ * Value `react` import declarations in source order. Type-only declarations
+ * (`import type { FC } from 'react'`) are excluded because a hook appended to
+ * one erases at compile time, leaving the wrapper call unbound at runtime.
+ */
+function reactImportsOf(program) {
+    return program.body.filter((statement) => statement.type === utils_1.AST_NODE_TYPES.ImportDeclaration &&
+        statement.source.value === REACT_MODULE &&
+        statement.importKind !== 'type');
+}
+/**
+ * A named specifier that binds `hookName` under its own name — the only shape
+ * that makes a bare `hookName(...)` call resolve to React's hook. An alias
+ * (`import { useMemo as useCallback }`) or a type-only specifier does not.
+ */
+function isHookSpecifier(specifier, hookName) {
+    return (specifier.type === utils_1.AST_NODE_TYPES.ImportSpecifier &&
+        specifier.importKind !== 'type' &&
+        specifier.imported.name === hookName &&
+        specifier.local.name === hookName);
+}
+/**
+ * Read the import state off the AST rather than a traversal flag: suggestions
+ * are computed per report and applied one at a time with a re-lint in between,
+ * so each has to be self-contained. A flag would also mis-handle a literal that
+ * precedes the import declaration in source order, since the
+ * `ImportDeclaration` visitor has not run for it yet.
+ */
+function importsHook(program, hookName) {
+    return reactImportsOf(program).some((declaration) => declaration.specifiers.some((specifier) => isHookSpecifier(specifier, hookName)));
+}
+/**
+ * Whether every declaration of a visible `hookName` binding is React's hook
+ * import. A local, a parameter, a namespace import, or an import from any other
+ * module all mean the generated wrapper would call something else.
+ */
+function bindsReactHook(variable, hookName) {
+    return (variable.defs.length > 0 &&
+        variable.defs.every((def) => {
+            const specifier = def.node;
+            if (!isHookSpecifier(specifier, hookName)) {
+                return false;
+            }
+            const declaration = specifier.parent;
+            return (declaration?.type === utils_1.AST_NODE_TYPES.ImportDeclaration &&
+                declaration.source.value === REACT_MODULE &&
+                declaration.importKind !== 'type');
+        }));
+}
+/**
+ * Edit that makes `hookName` resolve to React's hook, or null when the file
+ * already imports it. Extending an existing declaration is preferred over a new
+ * one so a file keeps a single `react` specifier list.
+ */
+function buildHookImportFix(fixer, program, hookName) {
+    if (importsHook(program, hookName)) {
+        return null;
+    }
+    const declarations = reactImportsOf(program);
+    const namedSpecifiers = declarations
+        .flatMap((declaration) => declaration.specifiers)
+        .filter((specifier) => specifier.type === utils_1.AST_NODE_TYPES.ImportSpecifier);
+    const lastNamedSpecifier = namedSpecifiers[namedSpecifiers.length - 1];
+    if (lastNamedSpecifier) {
+        return fixer.insertTextAfter(lastNamedSpecifier, `, ${hookName}`);
+    }
+    // A default import accepts a named list beside it
+    // (`import React, { useCallback } from 'react'`). A namespace import does
+    // not — `import * as React, { useCallback }` is a syntax error — so that
+    // shape, like a bare side-effect import, falls through to its own declaration.
+    const defaultSpecifier = declarations
+        .flatMap((declaration) => declaration.specifiers)
+        .find((specifier) => specifier.type === utils_1.AST_NODE_TYPES.ImportDefaultSpecifier);
+    if (defaultSpecifier) {
+        return fixer.insertTextAfter(defaultSpecifier, `, { ${hookName} }`);
+    }
+    const statement = `import { ${hookName} } from '${REACT_MODULE}';\n`;
+    const firstImport = program.body.find((node) => node.type === utils_1.AST_NODE_TYPES.ImportDeclaration);
+    const anchor = firstImport ?? program.body[0];
+    return anchor
+        ? fixer.insertTextBefore(anchor, statement)
+        : fixer.insertTextAfterRange([0, 0], statement);
+}
 /**
  * Builds memoization suggestions with dependency placeholders for developers.
  * @param node Literal node to wrap.
  * @param descriptor Literal metadata including memo hook.
  * @param sourceCode Source code utility for text extraction.
+ * @param context Rule context used to resolve the hook name at the call site.
  * @returns Suggestion array encouraging memoization with explicit deps TODO.
  */
-function buildMemoSuggestions(node, descriptor, sourceCode) {
+function buildMemoSuggestions(node, descriptor, sourceCode, context) {
     const initializerText = sourceCode.getText(node);
     const wrappedInitializer = descriptor.literalType === 'object literal'
         ? `(${initializerText})`
         : initializerText;
-    if (descriptor.literalType === 'inline function') {
-        return [
-            {
-                messageId: 'memoizeLiteralSuggestion',
-                data: {
-                    literalType: descriptor.literalType,
-                    memoHook: descriptor.memoHook,
-                },
-                fix(fixer) {
-                    return fixer.replaceText(node, `${descriptor.memoHook}(${initializerText}, [${TODO_DEPS_COMMENT}])`);
-                },
-            },
-        ];
-    }
+    const replacementText = descriptor.literalType === 'inline function'
+        ? `${descriptor.memoHook}(${initializerText}, [${TODO_DEPS_COMMENT}])`
+        : `${descriptor.memoHook}(() => ${wrappedInitializer}, [${TODO_DEPS_COMMENT}])`;
     return [
         {
             messageId: 'memoizeLiteralSuggestion',
@@ -651,7 +725,29 @@ function buildMemoSuggestions(node, descriptor, sourceCode) {
                 memoHook: descriptor.memoHook,
             },
             fix(fixer) {
-                return fixer.replaceText(node, `${descriptor.memoHook}(() => ${wrappedInitializer}, [${TODO_DEPS_COMMENT}])`);
+                // The wrapper is only correct if the hook name resolves to React's
+                // hook. A shadowing local/parameter would silently call that value
+                // instead, and an import of the same name from another module would
+                // collide with the inserted specifier, so decline the suggestion and
+                // leave the report for the author to migrate deliberately.
+                const existing = ASTHelpers_1.ASTHelpers.findVariableInScope(ASTHelpers_1.ASTHelpers.getScope(context, 
+                // Resolve from the declarator, not the literal: a function literal
+                // is its own scope, so its parameters would shadow a name that the
+                // wrapper call — placed outside it — never sees.
+                node.parent ?? node), descriptor.memoHook);
+                if (existing && !bindsReactHook(existing, descriptor.memoHook)) {
+                    return null;
+                }
+                // The import and the wrap are one atomic fix: emitted separately, the
+                // two disjoint ranges can be applied independently, stranding the
+                // wrapper without its binding.
+                const fixes = [];
+                const importFix = buildHookImportFix(fixer, sourceCode.ast, descriptor.memoHook);
+                if (importFix) {
+                    fixes.push(importFix);
+                }
+                fixes.push(fixer.replaceText(node, replacementText));
+                return fixes;
             },
         },
     ];
@@ -1538,7 +1634,7 @@ exports.reactMemoizeLiterals = (0, createRule_1.createRule)({
             // contexts (returns, JSX props, nested expressions) risk unsafe rewrites.
             const suggestions = node.parent?.type === utils_1.AST_NODE_TYPES.VariableDeclarator &&
                 node.parent.init === node
-                ? buildMemoSuggestions(node, descriptor, sourceCode)
+                ? buildMemoSuggestions(node, descriptor, sourceCode, context)
                 : undefined;
             context.report({
                 node,

package/package.json

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

package/release-manifest.json

@@ -1,4 +1,48 @@
 [
+  {
+    "version": "1.20.30",
+    "date": "2026-07-30T09:38:08.871Z",
+    "rules": [
+      {
+        "name": "enforce-safe-stringify",
+        "changeType": "fix",
+        "issues": [
+          1419
+        ],
+        "summary": "withhold the suggestion when `stringify` is already bound (closes #1419)"
+      },
+      {
+        "name": "prefer-document-flattening",
+        "changeType": "fix",
+        "issues": [
+          1420
+        ],
+        "summary": "anchor the shouldFlatten insertion on the trailing comma (closes #1420)"
+      },
+      {
+        "name": "react-memoize-literals",
+        "changeType": "fix",
+        "issues": [
+          1421
+        ],
+        "summary": "carry the react hook import with the wrapper (closes #1421)"
+      }
+    ]
+  },
+  {
+    "version": "1.20.29",
+    "date": "2026-07-30T08:31:47.570Z",
+    "rules": [
+      {
+        "name": "global-const-style",
+        "changeType": "fix",
+        "issues": [
+          1418
+        ],
+        "summary": "exempt bare-identifier binding aliases (closes #1418)"
+      }
+    ]
+  },
   {
     "version": "1.20.28",
     "date": "2026-07-30T07:59:36.776Z",