@blumintinc/eslint-plugin-blumint 1.21.4 → 1.21.5

package/lib/index.js

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

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

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

package/lib/rules/enforce-microdiff.js

@@ -112,6 +112,30 @@ const COMPETING_DIFF_MODULES = new Set([
     // '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.
 ]);
+/**
+ * The competing libraries whose calls are reported but never rewritten, because
+ * microdiff answers a different question than either of them does.
+ *
+ * jsdiff (`diff`) is a Myers sequence diff. `diffArrays(a, b)` returns runs of
+ * `{value, added, removed, count}`, so equal inputs yield one *kept* run where
+ * microdiff returns the empty list — `changes.length === 0` flips meaning under
+ * the rename — and a consumer reading `.added`, `.removed`, `.value` or
+ * `.count` gets `.type`, `.path` and `.oldValue` instead. Neither loss is a
+ * compile error, so nothing downstream flags it. Its optional third argument is
+ * a comparator bag with no counterpart in `Partial<MicrodiffOptions>`, which is
+ * a compile error (TS2345).
+ *
+ * `fast-diff` diffs STRINGS. Its operands satisfy neither half of microdiff's
+ * `TData extends Record<string, unknown> | unknown[]` bound, so that arm cannot
+ * emit a rewrite that compiles at all (TS2345).
+ *
+ * Detection is unchanged — both keep their entries in `DIFF_FUNCTION_NAMES` and
+ * `COMPETING_DIFF_MODULES` — because reaching for either where a structural
+ * per-path diff is wanted is still the finding. Only the rewrite is withheld,
+ * and the import retirement with it: dropping the declaration while the calls
+ * it binds stay behind is what would leave the file with an unbound name.
+ */
+const UNCONVERTIBLE_DIFF_MODULES = new Set(['diff', 'fast-diff']);
 /**
  * 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
@@ -162,7 +186,12 @@ function collectClaimableSpecifiers(program) {
                 .forEach((specifier) => claimable.add(specifier));
             return;
         }
-        if (COMPETING_DIFF_MODULES.has(source)) {
+        // A declaration no fix retires keeps every name it binds, so a `diff` it
+        // declares is not the fix's to write over: microdiff's import emitted
+        // beside a surviving `import { diff } from 'diff'` duplicates the binding
+        // (TS2300).
+        if (COMPETING_DIFF_MODULES.has(source) &&
+            !UNCONVERTIBLE_DIFF_MODULES.has(source)) {
             statement.specifiers.forEach((specifier) => claimable.add(specifier));
         }
     });
@@ -480,6 +509,7 @@ exports.enforceMicrodiff = (0, createRule_1.createRule)({
         schema: [],
         messages: {
             enforceMicrodiff: 'Use the microdiff library for object and array comparison operations',
+            enforceMicrodiffManual: 'Use the microdiff library for object and array comparison operations. Convert this {{importSource}} call by hand: it returns a different result shape than the structural change list microdiff produces.',
             enforceMicrodiffImport: 'Import diff from microdiff instead of {{importSource}}',
         },
     },
@@ -777,6 +807,12 @@ exports.enforceMicrodiff = (0, createRule_1.createRule)({
                             importSource,
                         },
                         fix(fixer) {
+                            // Every call this declaration serves is left for manual
+                            // conversion, so retiring it would strand each of them on a name
+                            // nothing binds.
+                            if (UNCONVERTIBLE_DIFF_MODULES.has(importSource)) {
+                                return null;
+                            }
                             // Decline rather than duplicate or shadow a `diff` this file
                             // already binds to something else, and rather than retire an
                             // import whose references no call fix rewrites. The report stands
@@ -853,6 +889,19 @@ exports.enforceMicrodiff = (0, createRule_1.createRule)({
                             if (ALLOWED_DIFF_MODULES.has(importSource)) {
                                 return;
                             }
+                            // A library microdiff does not stand in for is reported without
+                            // the rename. The substitution would compile at some of these
+                            // call sites and answer a different question there, which is a
+                            // loss nothing downstream can flag.
+                            if (UNCONVERTIBLE_DIFF_MODULES.has(importSource)) {
+                                reportedNodes.add(node);
+                                context.report({
+                                    node,
+                                    messageId: 'enforceMicrodiffManual',
+                                    data: { importSource },
+                                });
+                                return;
+                            }
                             // Report it if it's from any other tracked library
                             reportedNodes.add(node);
                             context.report({
@@ -874,6 +923,21 @@ exports.enforceMicrodiff = (0, createRule_1.createRule)({
                             if (!competingImport) {
                                 return;
                             }
+                            // The same withholding as above, reached by the other resolution
+                            // path: a default import and an unrecognised export name are both
+                            // bound here rather than tracked as specifiers, so gating only the
+                            // tracked branch would leave `import fastDiff from 'fast-diff'`
+                            // rewritten.
+                            const competingSource = String(competingImport.source.value);
+                            if (UNCONVERTIBLE_DIFF_MODULES.has(competingSource)) {
+                                reportedNodes.add(node);
+                                context.report({
+                                    node,
+                                    messageId: 'enforceMicrodiffManual',
+                                    data: { importSource: competingSource },
+                                });
+                                return;
+                            }
                             // Track this import name as used
                             usedImportNames.add(name);
                             // What the callee resolves to already settles this: the argument

package/lib/rules/flatten-push-calls.js

@@ -223,6 +223,206 @@ function canSafelyFix(group) {
         });
     });
 }
+/**
+ * `Array.prototype.push` is variadic, so merging consecutive appends onto one
+ * array preserves meaning. A method named `push` on any other receiver need not
+ * be: Next.js's `Router.push(url, as, options)` and react-router's
+ * `history.push(path, state)` are POSITIONAL, so folding two navigations into
+ * one call performs a single navigation with the address bar masked by the
+ * second argument. The merge is therefore gated on syntactic evidence that the
+ * receiver is an array, and stays silent without it — a missed consolidation
+ * costs far less than a fix that changes what the code does.
+ */
+const ARRAY_TYPE_NAMES = new Set(['Array', 'ReadonlyArray']);
+const ARRAY_FACTORY_METHODS = new Set(['from', 'of']);
+const ARRAY_RETURNING_METHODS = new Set([
+    'map',
+    'filter',
+    'slice',
+    'concat',
+    'split',
+]);
+/** Hooks whose array type argument describes the binding they hand back. */
+const ARRAY_STATE_HOOKS = new Set(['useState', 'useRef']);
+function isFunctionNode(node) {
+    return (node.type === utils_1.AST_NODE_TYPES.FunctionDeclaration ||
+        node.type === utils_1.AST_NODE_TYPES.FunctionExpression ||
+        node.type === utils_1.AST_NODE_TYPES.ArrowFunctionExpression);
+}
+function isArrayTypeNode(node) {
+    if (!node)
+        return false;
+    switch (node.type) {
+        case utils_1.AST_NODE_TYPES.TSArrayType:
+        case utils_1.AST_NODE_TYPES.TSTupleType:
+            return true;
+        case utils_1.AST_NODE_TYPES.TSTypeReference:
+            return (node.typeName.type === utils_1.AST_NODE_TYPES.Identifier &&
+                ARRAY_TYPE_NAMES.has(node.typeName.name));
+        case utils_1.AST_NODE_TYPES.TSTypeOperator:
+            return (node.operator === 'readonly' && isArrayTypeNode(node.typeAnnotation));
+        /** A union counts only when every member is an array, so `T[] | undefined`
+         * — whose `push` can be absent — does not. */
+        case utils_1.AST_NODE_TYPES.TSUnionType:
+            return node.types.every((member) => isArrayTypeNode(member));
+        default:
+            return false;
+    }
+}
+function isArrayAnnotation(annotation) {
+    return isArrayTypeNode(annotation?.typeAnnotation);
+}
+function hasArrayTypeArgument(call) {
+    return isArrayTypeNode(call.typeParameters?.params[0]);
+}
+function getCalleeName(call) {
+    const callee = unwrapExpression(call.callee);
+    if (callee.type === utils_1.AST_NODE_TYPES.Identifier)
+        return callee.name;
+    if (callee.type === utils_1.AST_NODE_TYPES.MemberExpression &&
+        !callee.computed &&
+        callee.property.type === utils_1.AST_NODE_TYPES.Identifier) {
+        return callee.property.name;
+    }
+    return null;
+}
+function isArrayStateHookCall(expression) {
+    if (!expression)
+        return false;
+    const node = unwrapExpression(expression);
+    if (node.type !== utils_1.AST_NODE_TYPES.CallExpression)
+        return false;
+    const name = getCalleeName(node);
+    return (name !== null && ARRAY_STATE_HOOKS.has(name) && hasArrayTypeArgument(node));
+}
+/**
+ * A call whose RESULT is an array. The state hooks are deliberately absent:
+ * `useRef<T[]>()` hands back a ref object and `useState<T[]>()` a tuple, so
+ * only the destructured head of that tuple is an array.
+ */
+function isArrayProducingCall(call) {
+    const callee = unwrapExpression(call.callee);
+    if (callee.type !== utils_1.AST_NODE_TYPES.MemberExpression ||
+        callee.computed ||
+        callee.property.type !== utils_1.AST_NODE_TYPES.Identifier) {
+        return false;
+    }
+    const object = unwrapExpression(callee.object);
+    if (object.type === utils_1.AST_NODE_TYPES.Identifier && object.name === 'Array') {
+        return ARRAY_FACTORY_METHODS.has(callee.property.name);
+    }
+    return ARRAY_RETURNING_METHODS.has(callee.property.name);
+}
+function isArrayInitializer(expression) {
+    if (!expression)
+        return false;
+    const node = unwrapExpression(expression);
+    switch (node.type) {
+        case utils_1.AST_NODE_TYPES.ArrayExpression:
+            return true;
+        case utils_1.AST_NODE_TYPES.NewExpression:
+            return (node.callee.type === utils_1.AST_NODE_TYPES.Identifier &&
+                node.callee.name === 'Array');
+        case utils_1.AST_NODE_TYPES.CallExpression:
+            return isArrayProducingCall(node);
+        default:
+            return false;
+    }
+}
+function isArrayDeclarator(declarator, name) {
+    if (declarator.id === name) {
+        return isArrayInitializer(declarator.init);
+    }
+    /**
+     * The head of a `useState<T[]>()` / `useRef<T[]>()` tuple holds the array
+     * itself. Every other destructured binding holds an ELEMENT of whatever was
+     * destructured, which says nothing about the binding.
+     */
+    return (declarator.id.type === utils_1.AST_NODE_TYPES.ArrayPattern &&
+        declarator.id.elements[0] === name &&
+        isArrayStateHookCall(declarator.init));
+}
+function isArrayParameterElement(param, name) {
+    switch (param.type) {
+        case utils_1.AST_NODE_TYPES.AssignmentPattern:
+            return param.left === name && isArrayInitializer(param.right);
+        /** A rest parameter binds an array by construction. */
+        case utils_1.AST_NODE_TYPES.RestElement:
+            return param.argument === name;
+        case utils_1.AST_NODE_TYPES.TSParameterProperty:
+            return isArrayParameterElement(param.parameter, name);
+        default:
+            return false;
+    }
+}
+function isArrayParameter(fn, name) {
+    return fn.params.some((param) => isArrayParameterElement(param, name));
+}
+function hasDefinitionArrayEvidence(def) {
+    const name = def.name;
+    /** A binding introduced by anything but a plain name carries no annotation. */
+    if (name.type !== utils_1.AST_NODE_TYPES.Identifier)
+        return false;
+    if (isArrayAnnotation(name.typeAnnotation))
+        return true;
+    if (def.node.type === utils_1.AST_NODE_TYPES.VariableDeclarator) {
+        return isArrayDeclarator(def.node, name);
+    }
+    return isFunctionNode(def.node) && isArrayParameter(def.node, name);
+}
+function isArrayParameterProperty(param, name) {
+    const binding = param.parameter.type === utils_1.AST_NODE_TYPES.AssignmentPattern
+        ? param.parameter.left
+        : param.parameter;
+    if (binding.type !== utils_1.AST_NODE_TYPES.Identifier || binding.name !== name) {
+        return false;
+    }
+    return (isArrayAnnotation(binding.typeAnnotation) ||
+        (param.parameter.type === utils_1.AST_NODE_TYPES.AssignmentPattern &&
+            isArrayInitializer(param.parameter.right)));
+}
+function hasClassPropertyArrayEvidence(classBody, name) {
+    return classBody.body.some((member) => {
+        if (member.type === utils_1.AST_NODE_TYPES.PropertyDefinition) {
+            if (getPropertyKey(member.key, Boolean(member.computed)) !== name) {
+                return false;
+            }
+            return (isArrayAnnotation(member.typeAnnotation) ||
+                isArrayInitializer(member.value));
+        }
+        if (member.type === utils_1.AST_NODE_TYPES.MethodDefinition &&
+            member.kind === 'constructor') {
+            return member.value.params.some((param) => param.type === utils_1.AST_NODE_TYPES.TSParameterProperty &&
+                isArrayParameterProperty(param, name));
+        }
+        return false;
+    });
+}
+/**
+ * The class whose fields describe `this` at this position. A plain function
+ * rebinds `this` to whatever calls it, so fields declared around it say nothing
+ * about the receiver; an arrow function keeps the lexical `this`, and a method's
+ * own function expression is the class's.
+ */
+function findEnclosingClassBody(node) {
+    let current = node.parent;
+    while (current) {
+        if (current.type === utils_1.AST_NODE_TYPES.ClassBody)
+            return current;
+        if (current.type === utils_1.AST_NODE_TYPES.FunctionDeclaration)
+            return null;
+        if (current.type === utils_1.AST_NODE_TYPES.FunctionExpression) {
+            const owner = current.parent;
+            const isClassMember = owner !== undefined &&
+                (owner.type === utils_1.AST_NODE_TYPES.MethodDefinition ||
+                    owner.type === utils_1.AST_NODE_TYPES.PropertyDefinition);
+            if (!isClassMember)
+                return null;
+        }
+        current = current.parent;
+    }
+    return null;
+}
 function isPushCallStatement(statement, sourceCode) {
     if (statement.type !== utils_1.AST_NODE_TYPES.ExpressionStatement)
         return null;
@@ -332,6 +532,73 @@ exports.flattenPushCalls = (0, createRule_1.createRule)({
     defaultOptions: [],
     create(context) {
         const sourceCode = context.getSourceCode();
+        /**
+         * Evidence is cached per binding rather than per receiver expression, so a
+         * long run of pushes onto one array resolves its declaration once.
+         */
+        const evidenceByVariable = new Map();
+        const evidenceByClassProperty = new Map();
+        let variablesByReference = null;
+        /**
+         * Resolution runs off the scope manager's own reference list rather than
+         * the scope of the visited node: `Program` yields the global scope, whose
+         * chain does not reach the module scope a top-level `const` lives in.
+         */
+        function resolveReference(identifier) {
+            if (!variablesByReference) {
+                const resolved = new Map();
+                sourceCode.scopeManager?.scopes.forEach((scope) => {
+                    scope.references.forEach((reference) => {
+                        resolved.set(reference.identifier, reference.resolved);
+                    });
+                });
+                variablesByReference = resolved;
+            }
+            return variablesByReference.get(identifier) ?? null;
+        }
+        function hasVariableArrayEvidence(variable) {
+            const cached = evidenceByVariable.get(variable);
+            if (cached !== undefined)
+                return cached;
+            const evidence = variable.defs.some((def) => hasDefinitionArrayEvidence(def));
+            evidenceByVariable.set(variable, evidence);
+            return evidence;
+        }
+        function hasThisPropertyArrayEvidence(receiver) {
+            const name = getPropertyKey(receiver.property, Boolean(receiver.computed));
+            if (name === null)
+                return false;
+            const classBody = findEnclosingClassBody(receiver);
+            if (!classBody)
+                return false;
+            const key = `${classBody.range[0]}:${name}`;
+            const cached = evidenceByClassProperty.get(key);
+            if (cached !== undefined)
+                return cached;
+            const evidence = hasClassPropertyArrayEvidence(classBody, name);
+            evidenceByClassProperty.set(key, evidence);
+            return evidence;
+        }
+        /**
+         * Whether the receiver is syntactically an array. Anything the source does
+         * not describe — an unresolved name, a member chain, a call result — counts
+         * as no evidence, which keeps the rule silent rather than guessing.
+         */
+        function hasArrayReceiverEvidence(receiver) {
+            const node = unwrapExpression(receiver);
+            if (node.type === utils_1.AST_NODE_TYPES.ArrayExpression)
+                return true;
+            if (node.type === utils_1.AST_NODE_TYPES.Identifier) {
+                const variable = resolveReference(node);
+                return variable !== null && hasVariableArrayEvidence(variable);
+            }
+            if (node.type === utils_1.AST_NODE_TYPES.MemberExpression &&
+                unwrapExpression(node.object).type ===
+                    utils_1.AST_NODE_TYPES.ThisExpression) {
+                return hasThisPropertyArrayEvidence(node);
+            }
+            return false;
+        }
         function buildChunks(call) {
             return call.arguments.map((arg) => ({
                 leading: sourceCode.getCommentsBefore(arg),
@@ -563,7 +830,11 @@ exports.flattenPushCalls = (0, createRule_1.createRule)({
                 return false;
             const totalArgs = group.reduce((count, entry) => count + entry.call.arguments.length, 0);
             const firstArgs = group[0].call.arguments.length;
-            return totalArgs > firstArgs && canSafelyFix(group);
+            if (totalArgs <= firstArgs || !canSafelyFix(group))
+                return false;
+            const receiver = group[0].call.callee
+                .object;
+            return hasArrayReceiverEvidence(receiver);
         }
         function reportViolation(group) {
             context.report({

package/package.json

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

package/release-manifest.json

@@ -1,4 +1,26 @@
 [
+  {
+    "version": "1.21.5",
+    "date": "2026-09-04T15:01:41.191Z",
+    "rules": [
+      {
+        "name": "enforce-microdiff",
+        "changeType": "fix",
+        "issues": [
+          2322
+        ],
+        "summary": "report jsdiff and fast-diff without rewriting them (closes #2322)"
+      },
+      {
+        "name": "flatten-push-calls",
+        "changeType": "fix",
+        "issues": [
+          2321
+        ],
+        "summary": "gate the merge on syntactic array evidence (closes #2321)"
+      }
+    ]
+  },
   {
     "version": "1.21.4",
     "date": "2026-09-04T11:47:38.427Z",