@blumintinc/eslint-plugin-blumint 1.20.96 → 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.96',
+        version: '1.20.98',
     },
     parseOptions: {
         ecmaVersion: 2020,

package/lib/rules/enforce-boolean-naming-prefixes.js

@@ -113,12 +113,25 @@ exports.enforceBooleanNamingPrefixes = (0, createRule_1.createRule)({
                     return true;
                 }
                 const nextChar = normalizedName.charAt(p.length);
-                // For SCREAMING_SNAKE_CASE or similar all-uppercase names,
-                // we require an underscore boundary.
+                // For SCREAMING_SNAKE_CASE or similar all-uppercase names the prefix must
+                // end at a separator, since case can no longer mark the word boundary
+                // (ISVALID stays unprefixed). Digits fused onto the prefix belong to that
+                // first segment rather than to the next word — ARE2_VALID is the
+                // UPPER_SNAKE spelling of are2Valid, which the camelCase branch below
+                // accepts — so a trailing digit run is consumed before the separator is
+                // examined, and the same separators the camelCase branch honours (`_`,
+                // `$`, end of name) close the segment. Only a digit run directly after
+                // the prefix qualifies: ARENA2_MAP still fails because a letter follows
+                // the prefix, and H2AS_ITEMS never reaches here because the prefix does
+                // not match the segment's start.
                 const isAllUppercase = normalizedName === normalizedName.toUpperCase() &&
                     /[a-z]/i.test(normalizedName);
                 if (isAllUppercase) {
-                    return nextChar === '_';
+                    const afterPrefix = normalizedName
+                        .slice(p.length)
+                        .replace(/^\d+/, '');
+                    const boundaryChar = afterPrefix.charAt(0);
+                    return (boundaryChar === '' || boundaryChar === '_' || boundaryChar === '$');
                 }
                 // For camelCase, the next char must be uppercase, a digit, or $
                 return (nextChar === '_' ||
@@ -710,6 +723,28 @@ exports.enforceBooleanNamingPrefixes = (0, createRule_1.createRule)({
                 expression.name === 'undefined') {
                 return 'nonBoolean';
             }
+            // A returned binding is governed by this very rule: a boolean variable,
+            // parameter or function must carry an approved prefix. So an unprefixed
+            // `id` — or the result of calling an unprefixed `compute(x)` — is not a
+            // boolean under the regime the rule enforces, and the callee's own name
+            // must not override that. Deciding here keeps the exemption in the body
+            // rather than in a return annotation, which `no-explicit-return-type`
+            // deletes (issue #1691).
+            //
+            // Member accesses (`source.flag`, `source.read()`) are deliberately
+            // excluded: property signatures are only enforced under
+            // `enforceForPropertySignatures` and third-party method names are outside
+            // this rule's reach, so an unprefixed member may legitimately yield a
+            // boolean and the callee's name keeps its say.
+            if (expression.type === utils_1.AST_NODE_TYPES.Identifier) {
+                return identifierIsBoolean(expression) ? 'boolean' : 'nonBoolean';
+            }
+            if (expression.type === utils_1.AST_NODE_TYPES.CallExpression &&
+                expression.callee.type === utils_1.AST_NODE_TYPES.Identifier) {
+                return callExpressionLooksBoolean(expression) === 'boolean'
+                    ? 'boolean'
+                    : 'nonBoolean';
+            }
             if (expression.type === utils_1.AST_NODE_TYPES.UnaryExpression) {
                 if (expression.operator === '!' || expression.operator === 'delete') {
                     return 'boolean';

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/lib/rules/enforce-positive-naming.js

@@ -973,6 +973,78 @@ function isDefinitelyNonBooleanExpression(node) {
             return false;
     }
 }
+// Operators whose result is always a boolean, regardless of operand types.
+const BOOLEAN_BINARY_OPERATORS = new Set([
+    '==',
+    '!=',
+    '===',
+    '!==',
+    '<',
+    '<=',
+    '>',
+    '>=',
+    'in',
+    'instanceof',
+]);
+/**
+ * Detects an expression that is definitively a boolean — a boolean literal, a
+ * negation, a comparison, or a branch/`Boolean()` call built from those. Opaque
+ * expressions (calls, identifiers, member accesses) yield no verdict here: they
+ * are the shapes a validator's body takes once its return annotation is gone,
+ * and assuming boolean for them is what produced the false positive in #1692.
+ */
+function isDefinitelyBooleanExpression(node) {
+    switch (node.type) {
+        case utils_1.AST_NODE_TYPES.Literal:
+            return typeof node.value === 'boolean';
+        case utils_1.AST_NODE_TYPES.UnaryExpression:
+            return node.operator === '!' || node.operator === 'delete';
+        case utils_1.AST_NODE_TYPES.BinaryExpression:
+            return BOOLEAN_BINARY_OPERATORS.has(node.operator);
+        case utils_1.AST_NODE_TYPES.LogicalExpression:
+            return (isDefinitelyBooleanExpression(node.left) &&
+                isDefinitelyBooleanExpression(node.right));
+        case utils_1.AST_NODE_TYPES.ConditionalExpression:
+            return (isDefinitelyBooleanExpression(node.consequent) &&
+                isDefinitelyBooleanExpression(node.alternate));
+        case utils_1.AST_NODE_TYPES.CallExpression:
+            // `Boolean(x)` is the one call whose result is boolean by construction.
+            return (node.callee.type === utils_1.AST_NODE_TYPES.Identifier &&
+                node.callee.name === 'Boolean');
+        case utils_1.AST_NODE_TYPES.TSAsExpression:
+        case utils_1.AST_NODE_TYPES.TSSatisfiesExpression:
+            // `x as boolean` asserts booleanness; `x as const` and other assertions
+            // say nothing, so the asserted expression decides.
+            return (isBooleanOnlyType(node.typeAnnotation) ||
+                isDefinitelyBooleanExpression(node.expression));
+        case utils_1.AST_NODE_TYPES.TSNonNullExpression:
+            return isDefinitelyBooleanExpression(node.expression);
+        default:
+            return false;
+    }
+}
+function classifyExpression(node) {
+    // A definitively non-boolean shape wins over a boolean one: a validator's
+    // `return 'Must not be blank'` proves the function is not a predicate even
+    // though its success path returns `true`.
+    if (isDefinitelyNonBooleanExpression(node))
+        return 'nonBoolean';
+    if (isDefinitelyBooleanExpression(node))
+        return 'boolean';
+    return 'indeterminate';
+}
+/**
+ * Combines the verdicts of a body's returns under the same precedence:
+ * non-boolean beats boolean, and boolean beats no verdict at all. An empty list
+ * (a body with no returns) is `indeterminate`.
+ */
+function combineReturnKinds(kinds) {
+    if (kinds.includes('nonBoolean'))
+        return 'nonBoolean';
+    if (kinds.includes('boolean'))
+        return 'boolean';
+    return 'indeterminate';
+}
 /**
  * Yields the immediate AST-node children of `node`, skipping the `parent`
  * back-reference so traversal only walks downward.
@@ -995,10 +1067,12 @@ function childNodesOf(node) {
     return children;
 }
 /**
- * Whether any `return` statement belonging to `fn`'s own body (not a nested
- * function's) yields a definitively non-boolean value.
+ * Classifies the `return` statements belonging to `fn`'s own body (not a nested
+ * function's). A bare `return;` carries no verdict, so it neither exempts the
+ * function nor keeps a sibling boolean return from deciding.
  */
-function blockReturnsNonBoolean(block) {
+function classifyBlockReturns(block) {
+    const kinds = [];
     const stack = [block];
     while (stack.length > 0) {
         const current = stack.pop();
@@ -1009,41 +1083,54 @@ function blockReturnsNonBoolean(block) {
                 current.type === utils_1.AST_NODE_TYPES.ArrowFunctionExpression)) {
             continue;
         }
-        if (current.type === utils_1.AST_NODE_TYPES.ReturnStatement &&
-            current.argument &&
-            isDefinitelyNonBooleanExpression(current.argument)) {
-            return true;
+        if (current.type === utils_1.AST_NODE_TYPES.ReturnStatement && current.argument) {
+            kinds.push(classifyExpression(current.argument));
         }
         for (const child of childNodesOf(current)) {
             stack.push(child);
         }
     }
-    return false;
+    return combineReturnKinds(kinds);
 }
 /**
- * Whether a function backing an `is`/`has`-prefixed name actually returns a
- * non-boolean value — e.g. a validator predicate returning `string | true`. An
+ * The booleanness of a function backing an `is`/`has`-prefixed name. An
  * explicit return-type annotation is authoritative; otherwise the body's own
- * `return` statements (or the concise-arrow expression) are inspected.
+ * `return` statements (or the concise-arrow expression) decide.
  */
-function functionReturnsNonBoolean(fn) {
+function classifyFunctionReturn(fn) {
     if (fn.returnType) {
-        return !isBooleanOnlyType(fn.returnType.typeAnnotation);
+        return isBooleanOnlyType(fn.returnType.typeAnnotation)
+            ? 'boolean'
+            : 'nonBoolean';
     }
     if (fn.body.type !== utils_1.AST_NODE_TYPES.BlockStatement) {
-        return isDefinitelyNonBooleanExpression(fn.body);
+        return classifyExpression(fn.body);
     }
-    return blockReturnsNonBoolean(fn.body);
+    return classifyBlockReturns(fn.body);
+}
+/**
+ * Whether a function backing an `is`/`has`-prefixed name must be exempt from
+ * boolean negative-naming. Only a function proven to return a boolean is
+ * flagged: a validator predicate returning `string | true` is exempt, and so is
+ * one whose returns are syntactically opaque (`=> validate(value)`). That
+ * matters because `no-explicit-return-type` deletes the very annotation that
+ * spells the validator's non-boolean return, leaving nothing but the name to go
+ * on — and guessing "boolean" from the name alone reports a rename that inverts
+ * the predicate's meaning (#1692). Preferring a false negative here is the
+ * repository's stated trade-off.
+ */
+function isExemptFromBooleanNaming(fn) {
+    return classifyFunctionReturn(fn) !== 'boolean';
 }
 /**
- * When a declarator/property value is a function, whether that function is a
- * non-boolean predicate that must be exempt from boolean negative-naming.
+ * When a declarator/property value is a function, whether that function is
+ * exempt from boolean negative-naming.
  */
-function isNonBooleanFunctionValue(node) {
+function isExemptFunctionValue(node) {
     return (!!node &&
         (node.type === utils_1.AST_NODE_TYPES.ArrowFunctionExpression ||
             node.type === utils_1.AST_NODE_TYPES.FunctionExpression) &&
-        functionReturnsNonBoolean(node));
+        isExemptFromBooleanNaming(node));
 }
 exports.enforcePositiveNaming = (0, createRule_1.createRule)({
     name: 'enforce-positive-naming',
@@ -1280,7 +1367,7 @@ exports.enforcePositiveNaming = (0, createRule_1.createRule)({
             // with `is`/`has` but is not a boolean, so its domain-correct negation
             // ("isNotBlank") must not be flagged. The name heuristic alone cannot
             // tell them apart; the initializer's return shape can.
-            if (isNonBooleanFunctionValue(node.init))
+            if (isExemptFunctionValue(node.init))
                 return;
             const variableName = node.id.name;
             const { isNegative, alternatives } = hasBooleanNegativeNaming(variableName);
@@ -1323,8 +1410,9 @@ exports.enforcePositiveNaming = (0, createRule_1.createRule)({
             if (!isBooleanLike(node.id || node))
                 return;
             // Skip validator predicates that return a non-boolean value (e.g.
-            // `string | true`), whose negation is the domain-correct term.
-            if (functionReturnsNonBoolean(node))
+            // `string | true`), whose negation is the domain-correct term, and any
+            // function whose returns give no syntactic verdict.
+            if (isExemptFromBooleanNaming(node))
                 return;
             const { isNegative, alternatives } = hasBooleanNegativeNaming(functionName);
             if (isNegative) {
@@ -1348,7 +1436,7 @@ exports.enforcePositiveNaming = (0, createRule_1.createRule)({
             if (!isBooleanLike(node.key))
                 return;
             // Skip validator predicates returning a non-boolean value.
-            if (isNonBooleanFunctionValue(node.value))
+            if (isExemptFunctionValue(node.value))
                 return;
             const methodName = node.key.name;
             const { isNegative, alternatives } = hasBooleanNegativeNaming(methodName);
@@ -1373,7 +1461,7 @@ exports.enforcePositiveNaming = (0, createRule_1.createRule)({
             if (!isBooleanLike(node.key))
                 return;
             // Skip validator predicates returning a non-boolean value.
-            if (isNonBooleanFunctionValue(node.value))
+            if (isExemptFunctionValue(node.value))
                 return;
             const propertyName = node.key.name;
             const { isNegative, alternatives } = hasBooleanNegativeNaming(propertyName);

package/lib/utils/harvestRuleTesterCases.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Collects every `RuleTester` case the suite declares WITHOUT executing any of
+ * them, by shadowing `run` on the shared tester instances and then loading each
+ * suite for its declarations alone.
+ *
+ * A guard that wants to exercise fixtures rather than documented snippets has no
+ * other way in. `src/tests/*.test.ts` call `RuleTester.run` at module scope, so
+ * importing one normally re-executes it — measured at 2350 tests, 2 minutes and
+ * 48 cross-file side-effect failures, which is why
+ * `recommended-config-fix-closure.test.ts` reads docs fenced blocks instead.
+ * Shadowing `run` before the load turns each of those calls into a declaration
+ * capture, so the cases are collected at the cost of loading the module and
+ * nothing more.
+ *
+ * The fixtures are worth reaching precisely because they are not the docs: a
+ * rule's `valid` list is written to sit on its carve-out boundaries, which is
+ * where a sibling fixer destroys an exemption. Every finding of that class
+ * (#1595-#1599, #1603, #1677-#1682) came from this corpus; the docs corpus
+ * caught none of them.
+ */
+/** A single `ruleTester.run(name, rule, tests)` call, captured but not run. */
+export type HarvestedSuite = {
+    /** The display name the suite passed to `run`. */
+    name: string;
+    /** Which shared tester export declared it, which fixes the parser. */
+    tester: string;
+    /** Basename of the declaring file, so a finding is reproducible by hand. */
+    file: string;
+    /**
+     * The rule object itself. Callers resolve a rule NAME from this by identity
+     * against the plugin's own map rather than from `name`: 100 of the suites
+     * pass a display name that is not a rule name (`requireMemo`,
+     * `prefer-next-dynamic (JSX scenarios)`, `no-hungarian-phone-number-test`),
+     * and name-keyed matching silently drops every one of them.
+     */
+    rule: unknown;
+    valid: readonly unknown[];
+    invalid: readonly unknown[];
+};
+export type HarvestResult = {
+    suites: HarvestedSuite[];
+    /** Files that threw while loading, `basename: message`. */
+    failures: string[];
+    /** Non-vacuity accounting: a silent drop here would fake a clean sweep. */
+    filesLoaded: number;
+    filesSkipped: number;
+};
+export declare function harvestRuleTesterCases(): HarvestResult;

package/lib/utils/harvestRuleTesterCases.js

@@ -0,0 +1,168 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.harvestRuleTesterCases = void 0;
+const fs = __importStar(require("fs"));
+const os = __importStar(require("os"));
+const path = __importStar(require("path"));
+const sharedTesters = __importStar(require("./ruleTester"));
+const TESTS_DIR = path.join(__dirname, '..', 'tests');
+/**
+ * Only suites that import the shared tester module can declare a case, since
+ * `src/tests/no-local-rule-tester.test.ts` forbids a locally-built tester. That
+ * makes the import a sound admission test rather than a heuristic, and it is
+ * what keeps this affordable: the ~28 files it excludes are the meta-suites
+ * (`fixer-type-safety`, `docs-examples-conformance`, `rule-crash-robustness`,
+ * this guard's own siblings) which run full corpus sweeps at module scope and
+ * cost more to load than every rule suite combined.
+ *
+ * Matching the import rather than a `ruleTesterTs.run(` call site is
+ * deliberate: `prefer-next-dynamic.test.ts` aliases the tester
+ * (`const jsx = ruleTesterJsx`) before calling `run`, so a call-site pattern
+ * drops it.
+ */
+const IMPORTS_SHARED_TESTER = /from\s+'\.\.\/utils\/ruleTester'/;
+/**
+ * Jest registers a test for every `describe`/`it` a loaded module calls, so
+ * loading 271 suites inside a suite would graft their entire test list onto
+ * this one. Neutralizing the registrars for the duration of the load keeps the
+ * captured declarations and discards the registrations.
+ *
+ * `describe` bodies still execute — several suites call `run` inside one, and
+ * skipping the body would drop those cases — but everything that would register
+ * or assert becomes a no-op.
+ */
+const REGISTRAR_GLOBALS = [
+    'it',
+    'test',
+    'beforeEach',
+    'afterEach',
+    'beforeAll',
+    'afterAll',
+];
+/* eslint-disable @typescript-eslint/no-explicit-any */
+const asAny = (value) => value;
+const noop = () => undefined;
+/** `it.each(rows)(name, fn)` is a call chain, so the stub needs the same shape. */
+const withEach = (fn) => {
+    fn.each = () => () => undefined;
+    fn.only = fn;
+    fn.skip = fn;
+    fn.todo = noop;
+    fn.failing = fn;
+    fn.concurrent = fn;
+    return fn;
+};
+function harvestRuleTesterCases() {
+    const suites = [];
+    const failures = [];
+    let currentFile = '';
+    let filesLoaded = 0;
+    let filesSkipped = 0;
+    const testerEntries = Object.entries(sharedTesters).filter(([, value]) => typeof asAny(value)?.run === 'function');
+    const originalRun = new Map();
+    for (const [key, tester] of testerEntries) {
+        originalRun.set(key, tester.run);
+        tester.run = (name, rule, tests) => {
+            const bag = asAny(tests) || {};
+            suites.push({
+                name,
+                tester: key,
+                file: currentFile,
+                rule,
+                valid: bag.valid || [],
+                invalid: bag.invalid || [],
+            });
+            return undefined;
+        };
+    }
+    const globalScope = global;
+    const savedGlobals = new Map();
+    const stub = (key, value) => {
+        savedGlobals.set(key, globalScope[key]);
+        globalScope[key] = value;
+    };
+    stub('describe', withEach((_name, body) => {
+        if (typeof body === 'function')
+            body();
+    }));
+    for (const key of REGISTRAR_GLOBALS)
+        stub(key, withEach(noop));
+    /**
+     * A handful of suites write fixture files at module scope, and
+     * `test-file-location-enforcement` writes them under
+     * `path.join(process.cwd(), '.cursor/tmp/...')` — a path it also `rmSync`s in
+     * an `afterAll` that the stubs above turn into a no-op. Loading it from the
+     * real working directory would therefore race that suite when it runs
+     * concurrently in another worker (its cleanup landing between this harvest's
+     * `mkdirSync` and `writeFileSync` throws ENOENT) and would strand fixtures in
+     * the repo when it does not. Pointing the working directory at a private
+     * scratch root for the duration of the load sends every cwd-derived write
+     * somewhere no other worker can see, and it is removed below.
+     *
+     * The paths the suites *record* are unaffected: they are made relative to the
+     * same cwd they were built from, so the harvested filenames come out
+     * identical either way.
+     */
+    const scratchRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'blumint-harvest-'));
+    const realCwd = process.cwd();
+    process.chdir(scratchRoot);
+    try {
+        const files = fs
+            .readdirSync(TESTS_DIR)
+            .filter((file) => file.endsWith('.test.ts'))
+            .sort();
+        for (const file of files) {
+            const fullPath = path.join(TESTS_DIR, file);
+            if (!IMPORTS_SHARED_TESTER.test(fs.readFileSync(fullPath, 'utf8'))) {
+                filesSkipped++;
+                continue;
+            }
+            currentFile = file;
+            try {
+                require(fullPath);
+                filesLoaded++;
+            }
+            catch (error) {
+                failures.push(`${file}: ${error?.message}`);
+            }
+        }
+    }
+    finally {
+        process.chdir(realCwd);
+        fs.rmSync(scratchRoot, { recursive: true, force: true });
+        for (const [key, tester] of testerEntries) {
+            const original = originalRun.get(key);
+            if (original)
+                tester.run = original;
+        }
+        for (const [key, value] of savedGlobals)
+            globalScope[key] = value;
+    }
+    return { suites, failures, filesLoaded, filesSkipped };
+}
+exports.harvestRuleTesterCases = harvestRuleTesterCases;
+/* eslint-enable @typescript-eslint/no-explicit-any */
+//# sourceMappingURL=harvestRuleTesterCases.js.map

package/package.json

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

package/release-manifest.json

@@ -1,4 +1,50 @@
 [
+  {
+    "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",
+    "rules": [
+      {
+        "name": "enforce-boolean-naming-prefixes",
+        "changeType": "fix",
+        "issues": [
+          1690,
+          1691
+        ],
+        "summary": "infer a callee's return from its body when the annotation is absent (closes #1691); accept a digit or $ fused onto an UPPER_SNAKE prefix (closes #1690)"
+      },
+      {
+        "name": "enforce-positive-naming",
+        "changeType": "fix",
+        "issues": [
+          1692
+        ],
+        "summary": "decline when a function's returns yield no verdict (closes #1692)"
+      }
+    ]
+  },
   {
     "version": "1.20.96",
     "date": "2026-08-04T07:23:58.552Z",