@blumintinc/eslint-plugin-blumint 1.20.97 → 1.20.98

package/lib/index.js

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

package/lib/rules/enforce-centralized-mock-firestore.js

@@ -3,7 +3,154 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.enforceCentralizedMockFirestore = void 0;
 const utils_1 = require("@typescript-eslint/utils");
 const createRule_1 = require("../utils/createRule");
+const importInsertion_1 = require("../utils/importInsertion");
 const MOCK_FIRESTORE_PATH = '../../../../../__test-utils__/mockFirestore';
+function isHorizontalWhitespace(character) {
+    return character === ' ' || character === '\t';
+}
+/**
+ * The span a retired declaration occupies, widened to its whole line only when
+ * the declaration is the sole occupant of that line. Anything else sharing the
+ * line — a live statement, a trailing comment, an `eslint-disable-line`
+ * directive — is outside the declaration's range and must survive the
+ * retirement: unrelated statements would become unbound references, and a
+ * deleted comment is the one damage class a formatter can never restore.
+ */
+function retirementEdit(text, start, end) {
+    const lineStart = text.lastIndexOf('\n', start - 1) + 1;
+    const newlineIndex = text.indexOf('\n', end);
+    const lineEnd = newlineIndex === -1 ? text.length : newlineIndex;
+    const before = text.slice(lineStart, start);
+    const after = text.slice(end, lineEnd);
+    if (/^\s*$/.test(before) && /^\s*$/.test(after)) {
+        return {
+            start: lineStart,
+            end: Math.min(lineEnd + 1, text.length),
+            text: '',
+        };
+    }
+    if (/^\s*$/.test(before)) {
+        // Code follows on this line, so the retired declaration hands over the
+        // indentation it was occupying rather than leaving the successor adrift.
+        let cursor = end;
+        while (isHorizontalWhitespace(text[cursor])) {
+            cursor++;
+        }
+        return { start, end: cursor, text: '' };
+    }
+    // Code precedes on this line; absorb the gap so no trailing space is left.
+    let cursor = start;
+    while (cursor > lineStart && isHorizontalWhitespace(text[cursor - 1])) {
+        cursor--;
+    }
+    return { start: cursor, end, text: '' };
+}
+/**
+ * Node types whose children are free-standing statements. A declaration
+ * anywhere else — a `for (const mockFirestore of …)` head, say — cannot be
+ * excised without leaving the enclosing construct malformed.
+ */
+const STATEMENT_CONTAINERS = new Set([
+    utils_1.AST_NODE_TYPES.Program,
+    utils_1.AST_NODE_TYPES.BlockStatement,
+    utils_1.AST_NODE_TYPES.StaticBlock,
+    utils_1.AST_NODE_TYPES.SwitchCase,
+    utils_1.AST_NODE_TYPES.TSModuleBlock,
+]);
+/**
+ * Widens a declaration to the `export` that fronts it, whose keyword lives
+ * outside the declaration's own range and would otherwise be stranded.
+ */
+function retirableStatement(declaration) {
+    const statement = declaration.parent?.type === utils_1.AST_NODE_TYPES.ExportNamedDeclaration
+        ? declaration.parent
+        : declaration;
+    return statement.parent &&
+        STATEMENT_CONTAINERS.has(statement.parent.type)
+        ? statement
+        : undefined;
+}
+function retiredSpan(node) {
+    const parent = node.parent;
+    if (parent?.type === utils_1.AST_NODE_TYPES.VariableDeclaration) {
+        const { declarations } = parent;
+        if (declarations.length === 1) {
+            const statement = retirableStatement(parent);
+            if (!statement) {
+                return undefined;
+            }
+            return {
+                start: statement.range[0],
+                end: statement.range[1],
+                whole: true,
+            };
+        }
+        const index = declarations.indexOf(node);
+        if (index > 0) {
+            return {
+                start: declarations[index - 1].range[1],
+                end: node.range[1],
+                whole: false,
+            };
+        }
+        if (index === 0) {
+            // Reach forward to the next declarator instead of backward past the
+            // `const`, whose trailing space still belongs to the survivors.
+            return {
+                start: node.range[0],
+                end: declarations[1].range[0],
+                whole: false,
+            };
+        }
+        return undefined;
+    }
+    if (node.type === utils_1.AST_NODE_TYPES.PropertyDefinition) {
+        return { start: node.range[0], end: node.range[1], whole: true };
+    }
+    return undefined;
+}
+/**
+ * Collapses edits that touch, so an overlap can never rewrite a range twice.
+ */
+function mergeEdits(edits) {
+    const sorted = [...edits].sort((a, b) => a.start - b.start || a.end - b.end);
+    const merged = [];
+    for (const edit of sorted) {
+        const last = merged[merged.length - 1];
+        if (last && edit.start < last.end) {
+            last.end = Math.max(last.end, edit.end);
+            last.text += edit.text;
+            continue;
+        }
+        merged.push({ ...edit });
+    }
+    return merged;
+}
+function editOffset(anchor) {
+    return anchor.kind === 'before' ? anchor.target.range[0] : anchor.index;
+}
+/**
+ * Where the import may be spliced in given the edits retiring the local mock.
+ *
+ * Widening to the anchor's line start is what lets the emitted
+ * `${indent}import …\n` leave the displaced statement on the indentation it
+ * already had, but that is sound only while whitespace is all that precedes
+ * the anchor: a `'use client';` sharing the anchor's line would be demoted by
+ * an insertion at column 0. When the resulting position still falls inside a
+ * retirement — the anchor statement is itself the declaration being retired,
+ * and the retirement claims the indentation ahead of it — the insertion moves
+ * to that edit's start, since ESLint rejects a fix nested inside another.
+ */
+function importPlacement(sourceCode, anchor, edits) {
+    const anchorStart = editOffset(anchor);
+    const lineStart = sourceCode.text.lastIndexOf('\n', anchorStart - 1) + 1;
+    const placement = /^[ \t]*$/.test(sourceCode.text.slice(lineStart, anchorStart))
+        ? (0, importInsertion_1.importAnchorLineStart)(sourceCode, anchor)
+        : anchor;
+    const offset = editOffset(placement);
+    const enclosing = edits.find((edit) => edit.start < offset && offset < edit.end);
+    return enclosing ? { kind: 'index', index: enclosing.start } : placement;
+}
 exports.enforceCentralizedMockFirestore = (0, createRule_1.createRule)({
     name: 'enforce-centralized-mock-firestore',
     meta: {
@@ -149,85 +296,66 @@ exports.enforceCentralizedMockFirestore = (0, createRule_1.createRule)({
                             requiredPath: MOCK_FIRESTORE_PATH,
                         },
                         fix(fixer) {
-                            // Instead of trying to modify the code incrementally, we'll generate the entire fixed code
                             const originalText = sourceCode.getText();
-                            const lines = originalText.split('\n');
-                            // Find the indentation of the code
-                            const indentMatch = lines[0].match(/^(\s*)/);
-                            const indent = indentMatch ? indentMatch[1] : '';
-                            // Create the import statement
-                            const importLine = `${indent}import { mockFirestore } from '${MOCK_FIRESTORE_PATH}';`;
-                            // Find all the lines that need to be removed
-                            const linesToRemove = new Set();
-                            // Process all nodes that need to be removed
-                            mockFirestoreNodes.forEach((node) => {
-                                const startLine = sourceCode.getLocFromIndex(node.range[0]).line - 1;
-                                const endLine = sourceCode.getLocFromIndex(node.range[1]).line - 1;
-                                if (node.parent?.type === utils_1.AST_NODE_TYPES.VariableDeclaration) {
-                                    // If it's the only declarator, remove the entire declaration
-                                    if (node.parent.declarations.length === 1) {
-                                        const declStartLine = sourceCode.getLocFromIndex(node.parent.range[0]).line - 1;
-                                        const declEndLine = sourceCode.getLocFromIndex(node.parent.range[1]).line - 1;
-                                        for (let i = declStartLine; i <= declEndLine; i++) {
-                                            linesToRemove.add(i);
-                                        }
-                                    }
-                                    else {
-                                        // Otherwise, just remove this declarator
-                                        for (let i = startLine; i <= endLine; i++) {
-                                            linesToRemove.add(i);
-                                        }
-                                    }
-                                }
-                                else if (node.type === utils_1.AST_NODE_TYPES.PropertyDefinition) {
-                                    // Remove class property
-                                    for (let i = startLine; i <= endLine; i++) {
-                                        linesToRemove.add(i);
-                                    }
+                            // Retire each declaration by its own character range. Line
+                            // indices would take every other occupant of those lines with
+                            // them.
+                            const removals = [];
+                            for (const node of mockFirestoreNodes) {
+                                const span = retiredSpan(node);
+                                if (!span) {
+                                    // A declaration that cannot be excised cleanly gets no
+                                    // autofix at all: leaving it behind while adding the import
+                                    // would report forever, and cutting it anyway would emit
+                                    // code that no longer parses.
+                                    return null;
                                 }
-                            });
+                                removals.push(span.whole
+                                    ? retirementEdit(originalText, span.start, span.end)
+                                    : { start: span.start, end: span.end, text: '' });
+                            }
                             // Replace custom mockFirestore references with the standard one
                             const replacements = [];
                             // Add replacements for custom mockFirestore names
                             customMockFirestoreCallExpressions.forEach((node) => {
                                 if (node.callee.type === utils_1.AST_NODE_TYPES.Identifier) {
-                                    replacements.push([
-                                        node.callee.range[0],
-                                        node.callee.name,
-                                        'mockFirestore',
-                                    ]);
+                                    replacements.push({
+                                        start: node.callee.range[0],
+                                        end: node.callee.range[1],
+                                        text: 'mockFirestore',
+                                    });
                                 }
                             });
                             // Add replacements for this.mockFirestore
                             thisExpressions.forEach((expr) => {
-                                replacements.push([
-                                    expr.range[0],
-                                    sourceCode.getText(expr),
-                                    'mockFirestore',
-                                ]);
+                                replacements.push({
+                                    start: expr.range[0],
+                                    end: expr.range[1],
+                                    text: 'mockFirestore',
+                                });
                             });
-                            // Sort replacements in reverse order to avoid range issues
-                            replacements.sort((a, b) => b[0] - a[0]);
-                            // Apply replacements to the original text
-                            let fixedText = originalText;
-                            for (const [pos, oldText, newText] of replacements) {
-                                fixedText =
-                                    fixedText.substring(0, pos) +
-                                        newText +
-                                        fixedText.substring(pos + oldText.length);
-                            }
-                            // Filter out the lines to remove
-                            const fixedLines = fixedText
-                                .split('\n')
-                                .filter((_, i) => !linesToRemove.has(i));
-                            // Add the import statement at the beginning
+                            // A reference inside a retired declaration goes away with it, so
+                            // rewriting it would only fight the removal for the same range.
+                            const survivingReplacements = replacements.filter((replacement) => !removals.some((removal) => replacement.start >= removal.start &&
+                                replacement.end <= removal.end));
+                            const edits = mergeEdits([...removals, ...survivingReplacements]);
+                            // Every edit is bounded to the characters it owns. Rebuilding
+                            // the file and writing it over the `Program` node instead would
+                            // emit whatever precedes `Program.range[0]` — a header comment,
+                            // a `@ts-nocheck`, a license block — a second time, and would
+                            // claim a fix range spanning the file, which wins every pass-1
+                            // fixer race and suppresses sibling rules' fixes.
+                            const fixes = edits.map(({ start, end, text }) => fixer.replaceTextRange([start, end], text));
                             if (!hasCentralizedImport) {
-                                fixedLines.unshift(importLine);
+                                // The shared anchor keeps the import below the file's
+                                // prologue: spliced above a `'use client'` / `'use server'`
+                                // directive it demotes the directive to a plain expression,
+                                // and above a `#!` shebang it leaves the file unparseable.
+                                const anchor = (0, importInsertion_1.importInsertionAnchor)(sourceCode);
+                                const indent = (0, importInsertion_1.importAnchorIndent)(sourceCode, anchor);
+                                fixes.push((0, importInsertion_1.insertAtImportAnchor)(sourceCode, fixer, importPlacement(sourceCode, anchor, edits), `${indent}import { mockFirestore } from '${MOCK_FIRESTORE_PATH}';\n`));
                             }
-                            // Join the lines back together
-                            const result = fixedLines.join('\n');
-                            // Return the fixed text
-                            return fixer.replaceText(sourceCode.ast, result);
+                            return fixes;
                         },
                     });
                 }

package/lib/rules/enforce-microdiff.js

@@ -207,6 +207,98 @@ function isRewrittenCallee(identifier) {
         parent.callee === identifier &&
         hasRewritableArity(parent));
 }
+/**
+ * The node types that open a scope of their own. The body walk stops at them
+ * because the emitted `diff` is only checked against the reported function's
+ * scope: a comparison inside a callback whose parameter is named `diff` would
+ * be rewritten into a call on that parameter, with no diagnostic to show for
+ * it.
+ */
+const FUNCTION_NODE_TYPES = new Set([
+    utils_1.AST_NODE_TYPES.ArrowFunctionExpression,
+    utils_1.AST_NODE_TYPES.FunctionDeclaration,
+    utils_1.AST_NODE_TYPES.FunctionExpression,
+]);
+/**
+ * Whether an expression is a call of `JSON.stringify`. The callee's shape
+ * decides rather than the source text, so a `stringify` read off anything but
+ * `JSON` — a local serializer bound under the same property name — keeps its
+ * call site.
+ */
+function isJsonStringify(node) {
+    return (node.type === utils_1.AST_NODE_TYPES.CallExpression &&
+        node.callee.type === utils_1.AST_NODE_TYPES.MemberExpression &&
+        node.callee.object.type === utils_1.AST_NODE_TYPES.Identifier &&
+        node.callee.object.name === 'JSON' &&
+        node.callee.property.type === utils_1.AST_NODE_TYPES.Identifier &&
+        node.callee.property.name === 'stringify');
+}
+/**
+ * The stringify comparison an expression makes, or null for every other
+ * expression.
+ *
+ * A zero-argument `JSON.stringify()` yields null. The indexed argument read is
+ * typed non-optional, so nothing else forces the check, and there is no operand
+ * to hand `diff`.
+ */
+function toStringifyComparison(node) {
+    if (node.type !== utils_1.AST_NODE_TYPES.BinaryExpression ||
+        (node.operator !== '===' && node.operator !== '!==')) {
+        return null;
+    }
+    if (!isJsonStringify(node.left) || !isJsonStringify(node.right)) {
+        return null;
+    }
+    const left = node.left.arguments[0];
+    const right = node.right.arguments[0];
+    if (!left || !right) {
+        return null;
+    }
+    return { node, left, right, isEqual: node.operator === '===' };
+}
+/**
+ * Every stringify comparison `body` makes in its own scope, nested functions
+ * excluded.
+ *
+ * A rewrite driven by the enclosing function's parameter list answers a
+ * question the source never asked: `JSON.stringify(a.settings) !==
+ * JSON.stringify(b.settings)` compares two properties, and the signature's
+ * operands widen that to the whole objects. Reading the comparison itself is
+ * also what makes a destructuring parameter a non-issue, since the operands
+ * name what to diff whatever the signature binds.
+ */
+function collectStringifyComparisons(body) {
+    const comparisons = [];
+    const pending = [body];
+    while (pending.length > 0) {
+        const current = pending.pop();
+        if (current !== body && FUNCTION_NODE_TYPES.has(current.type)) {
+            continue;
+        }
+        const comparison = toStringifyComparison(current);
+        if (comparison) {
+            comparisons.push(comparison);
+        }
+        for (const key in current) {
+            // The parent link closes a cycle over every node in the file.
+            if (key === 'parent') {
+                continue;
+            }
+            const value = current[key];
+            if (Array.isArray(value)) {
+                value.forEach((child) => {
+                    if (ASTHelpers_1.ASTHelpers.isNode(child)) {
+                        pending.push(child);
+                    }
+                });
+            }
+            else if (ASTHelpers_1.ASTHelpers.isNode(value)) {
+                pending.push(value);
+            }
+        }
+    }
+    return comparisons;
+}
 /**
  * Whether a bare `diff` written at `scope` reaches microdiff's function.
  * Resolving through the scope chain catches both failure modes: a module-scope
@@ -354,6 +446,17 @@ exports.enforceMicrodiff = (0, createRule_1.createRule)({
                 : '\n\n';
             return (0, importInsertion_1.insertAtImportAnchor)(sourceCode, fixer, anchor, `${MICRODIFF_IMPORT}${separator}`);
         }
+        /**
+         * The microdiff form of a stringify comparison: a change list whose
+         * emptiness carries the sense of the operator it replaces, so `===` becomes
+         * `.length === 0` and `!==` becomes `.length > 0`.
+         */
+        function buildDiffComparison(comparison) {
+            const left = sourceCode.getText(comparison.left);
+            const right = sourceCode.getText(comparison.right);
+            const emptiness = comparison.isEqual ? '.length === 0' : '.length > 0';
+            return `${DIFF_NAME}(${left}, ${right})${emptiness}`;
+        }
         // 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
@@ -559,46 +662,29 @@ exports.enforceMicrodiff = (0, createRule_1.createRule)({
                     return;
                 }
                 // Check for JSON.stringify comparison pattern
-                if ((node.operator === '===' || node.operator === '!==') &&
-                    node.left.type === utils_1.AST_NODE_TYPES.CallExpression &&
-                    node.right.type === utils_1.AST_NODE_TYPES.CallExpression) {
-                    const isJsonStringify = (expr) => {
-                        return (expr.callee.type === utils_1.AST_NODE_TYPES.MemberExpression &&
-                            expr.callee.object.type === utils_1.AST_NODE_TYPES.Identifier &&
-                            expr.callee.object.name === 'JSON' &&
-                            expr.callee.property.type === utils_1.AST_NODE_TYPES.Identifier &&
-                            expr.callee.property.name === 'stringify');
-                    };
-                    if (isJsonStringify(node.left) && isJsonStringify(node.right)) {
-                        const leftArg = node.left.arguments[0];
-                        const rightArg = node.right.arguments[0];
-                        // A zero-argument JSON.stringify() leaves these undefined. The
-                        // indexed read is typed non-optional, so nothing forces the check.
-                        if (!leftArg || !rightArg) {
-                            return;
-                        }
-                        if (isObjectOrArrayType(leftArg) && isObjectOrArrayType(rightArg)) {
-                            reportedNodes.add(node);
-                            const isEqual = node.operator === '===';
-                            context.report({
-                                node,
-                                messageId: 'enforceMicrodiff',
-                                fix(fixer) {
-                                    if (!canEmitDiffAt(node)) {
-                                        return null;
-                                    }
-                                    const compareFix = fixer.replaceText(node, `${DIFF_NAME}(${sourceCode.getText(leftArg)}, ${sourceCode.getText(rightArg)})${isEqual ? '.length === 0' : '.length > 0'}`);
-                                    // The comparison this rewrites almost always sits inside a
-                                    // function, and the `diff` it emits needs an import whatever
-                                    // encloses it. Deciding on the enclosing node left every
-                                    // nested comparison calling a `diff` nothing bound.
-                                    const importFix = buildMicrodiffImportFix(fixer);
-                                    return importFix ? [importFix, compareFix] : compareFix;
-                                },
-                            });
-                        }
-                    }
+                const comparison = toStringifyComparison(node);
+                if (!comparison ||
+                    !isObjectOrArrayType(comparison.left) ||
+                    !isObjectOrArrayType(comparison.right)) {
+                    return;
                 }
+                reportedNodes.add(node);
+                context.report({
+                    node,
+                    messageId: 'enforceMicrodiff',
+                    fix(fixer) {
+                        if (!canEmitDiffAt(node)) {
+                            return null;
+                        }
+                        const compareFix = fixer.replaceText(node, buildDiffComparison(comparison));
+                        // The comparison this rewrites almost always sits inside a
+                        // function, and the `diff` it emits needs an import whatever
+                        // encloses it. Deciding on the enclosing node left every nested
+                        // comparison calling a `diff` nothing bound.
+                        const importFix = buildMicrodiffImportFix(fixer);
+                        return importFix ? [importFix, compareFix] : compareFix;
+                    },
+                });
             },
             // Check for custom deep comparison functions
             FunctionDeclaration(node) {
@@ -629,29 +715,27 @@ exports.enforceMicrodiff = (0, createRule_1.createRule)({
                             bodyText.includes('JSON.stringify') &&
                             bodyText.includes('!==')) {
                             reportedNodes.add(node);
-                            // The operands are the parameter *names*, not the text of the
-                            // parameters: a typed parameter's text carries its annotation,
-                            // and `diff(oldConfig: Config, ...)` does not parse. A parameter
-                            // that binds no single name — a destructuring or rest pattern —
-                            // has no operand to pass, so the report stands without a fix.
-                            const [firstParam, secondParam] = node.params;
-                            const operands = firstParam.type === utils_1.AST_NODE_TYPES.Identifier &&
-                                secondParam.type === utils_1.AST_NODE_TYPES.Identifier
-                                ? [firstParam.name, secondParam.name]
-                                : null;
+                            // Exactly one comparison is the condition for a fix. With none
+                            // there is no expression to rewrite, and with several the rule
+                            // cannot tell which one the function's answer turns on, so the
+                            // report stands on its own.
+                            const comparisons = collectStringifyComparisons(body);
+                            const comparison = comparisons.length === 1 ? comparisons[0] : null;
                             context.report({
                                 node,
                                 messageId: 'enforceMicrodiff',
                                 fix(fixer) {
-                                    if (!operands || !canEmitDiffAt(node)) {
+                                    if (!comparison || !canEmitDiffAt(node)) {
                                         return null;
                                     }
-                                    // Only the body is rewritten, so the signature keeps its type
-                                    // annotations, its modifiers, and any `export` in front of
-                                    // it. Replacing the declaration wholesale used to drop those
-                                    // and, when it prefixed the import, put an `import` inside
-                                    // whatever enclosed the function.
-                                    const bodyFix = fixer.replaceText(body, `{\n  return ${DIFF_NAME}(${operands[0]}, ${operands[1]}).length > 0;\n}`);
+                                    // Only the comparison's own range is rewritten. The signature
+                                    // keeps its type annotations, its modifiers and any `export`
+                                    // in front of it, and the body keeps everything the
+                                    // comparison shares it with: side effects, guard clauses,
+                                    // locals, and the comments around them. Re-emitting the body
+                                    // as a single return drops all of that silently — the fix
+                                    // compiles, so nothing downstream flags the loss.
+                                    const bodyFix = fixer.replaceText(comparison.node, buildDiffComparison(comparison));
                                     const importFix = buildMicrodiffImportFix(fixer);
                                     return importFix ? [importFix, bodyFix] : bodyFix;
                                 },

package/package.json

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

package/release-manifest.json

@@ -1,4 +1,27 @@
 [
+  {
+    "version": "1.20.98",
+    "date": "2026-08-04T10:58:56.821Z",
+    "rules": [
+      {
+        "name": "enforce-centralized-mock-firestore",
+        "changeType": "fix",
+        "issues": [
+          1694,
+          1695
+        ],
+        "summary": "place the import by anchor instead of rewriting the Program (closes #1695); retire declarations by range, not by line index (closes #1694)"
+      },
+      {
+        "name": "enforce-microdiff",
+        "changeType": "fix",
+        "issues": [
+          1693
+        ],
+        "summary": "rewrite the comparison in place instead of the whole body (closes #1693)"
+      }
+    ]
+  },
   {
     "version": "1.20.97",
     "date": "2026-08-04T08:50:14.394Z",