@blumintinc/eslint-plugin-blumint 1.20.118 → 1.20.120

package/lib/index.js

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

package/lib/rules/enforce-firestore-doc-ref-generic.js

@@ -11,6 +11,7 @@ exports.enforceFirestoreDocRefGeneric = void 0;
 const utils_1 = require("@typescript-eslint/utils");
 const createRule_1 = require("../utils/createRule");
 const ASTHelpers_1 = require("../utils/ASTHelpers");
+const lexicalScope_1 = require("../utils/lexicalScope");
 /** The Firestore reference types that carry a document-shape generic. */
 const REFERENCE_TYPE_NAMES = new Set([
     'DocumentReference',
@@ -38,20 +39,6 @@ const referenceTypeNameOf = (typeName) => {
     }
     return undefined;
 };
-/** Statement containers a type declaration can be a direct child of. */
-function statementsOf(node) {
-    switch (node.type) {
-        case utils_1.AST_NODE_TYPES.Program:
-        case utils_1.AST_NODE_TYPES.BlockStatement:
-        case utils_1.AST_NODE_TYPES.TSModuleBlock:
-        case utils_1.AST_NODE_TYPES.StaticBlock:
-            return node.body;
-        case utils_1.AST_NODE_TYPES.SwitchCase:
-            return node.consequent;
-        default:
-            return undefined;
-    }
-}
 /**
  * The type declaration a statement makes, looking through `export`.
  *
@@ -61,10 +48,7 @@ function statementsOf(node) {
  * distinction the document shape knows anything about.
  */
 function typeDeclarationNamed(statement, name) {
-    const declared = statement.type === utils_1.AST_NODE_TYPES.ExportNamedDeclaration &&
-        statement.declaration
-        ? statement.declaration
-        : statement;
+    const declared = (0, lexicalScope_1.declarationOf)(statement);
     if ((declared.type === utils_1.AST_NODE_TYPES.TSInterfaceDeclaration ||
         declared.type === utils_1.AST_NODE_TYPES.TSTypeAliasDeclaration) &&
         declared.id.name === name) {
@@ -83,20 +67,15 @@ function typeDeclarationNamed(statement, name) {
  * dropped the nested-`any` check rather than reporting anything.
  */
 function declarationOfType(from, name) {
-    let current = from;
-    while (current) {
-        const statements = statementsOf(current);
-        if (statements) {
-            for (const statement of statements) {
-                const declaration = typeDeclarationNamed(statement, name);
-                if (declaration) {
-                    return declaration;
-                }
+    return (0, lexicalScope_1.resolveInEnclosingScopes)(from, (statements) => {
+        for (const statement of statements) {
+            const declaration = typeDeclarationNamed(statement, name);
+            if (declaration) {
+                return declaration;
             }
         }
-        current = current.parent;
-    }
-    return undefined;
+        return undefined;
+    });
 }
 /**
  * @type {import('eslint').Rule.RuleModule}

package/lib/rules/enforce-firestore-set-merge.js

@@ -5,6 +5,7 @@ const utils_1 = require("@typescript-eslint/utils");
 const createRule_1 = require("../utils/createRule");
 const ASTHelpers_1 = require("../utils/ASTHelpers");
 const disableDirectives_1 = require("../utils/disableDirectives");
+const lexicalScope_1 = require("../utils/lexicalScope");
 const FIRESTORE_MODULES = new Set(['firebase/firestore', 'firebase-admin']);
 const UPDATE_DOC = 'updateDoc';
 const SET_DOC = 'setDoc';
@@ -192,20 +193,6 @@ function isPrimitiveLiteral(node) {
         typeof value === 'boolean' ||
         typeof value === 'bigint');
 }
-/** Statement containers a declaration can be a direct child of. */
-function statementsOf(node) {
-    switch (node.type) {
-        case utils_1.AST_NODE_TYPES.Program:
-        case utils_1.AST_NODE_TYPES.BlockStatement:
-        case utils_1.AST_NODE_TYPES.TSModuleBlock:
-        case utils_1.AST_NODE_TYPES.StaticBlock:
-            return node.body;
-        case utils_1.AST_NODE_TYPES.SwitchCase:
-            return node.consequent;
-        default:
-            return undefined;
-    }
-}
 /** Whether a declarator is initialized from a `<x>.firestore()` call. */
 function initializesFirestore(declarator) {
     const { init } = declarator;
@@ -225,10 +212,7 @@ function initializesFirestore(declarator) {
  * "find the in-file declaration that carries the evidence" purpose.
  */
 function declaresFirestoreInstance(statement) {
-    const declaration = statement.type === utils_1.AST_NODE_TYPES.ExportNamedDeclaration &&
-        statement.declaration
-        ? statement.declaration
-        : statement;
+    const declaration = (0, lexicalScope_1.declarationOf)(statement);
     return (declaration.type === utils_1.AST_NODE_TYPES.VariableDeclaration &&
         declaration.declarations.some(initializesFirestore));
 }
@@ -244,15 +228,9 @@ function declaresFirestoreInstance(statement) {
  * falls through to the next one out instead of answering for the whole chain.
  */
 function hasFirestoreInstanceInScope(node) {
-    let current = node;
-    while (current) {
-        const statements = statementsOf(current);
-        if (statements?.some(declaresFirestoreInstance)) {
-            return true;
-        }
-        current = current.parent;
-    }
-    return false;
+    return ((0, lexicalScope_1.resolveInEnclosingScopes)(node, (statements) => statements.some((statement) => declaresFirestoreInstance(statement))
+        ? true
+        : undefined) === true);
 }
 exports.enforceFirestoreSetMerge = (0, createRule_1.createRule)({
     name: 'enforce-firestore-set-merge',
@@ -303,16 +281,13 @@ exports.enforceFirestoreSetMerge = (0, createRule_1.createRule)({
             }
             const classes = new Map();
             for (const statement of statements) {
-                const declaration = statement.type === utils_1.AST_NODE_TYPES.ExportNamedDeclaration ||
-                    statement.type === utils_1.AST_NODE_TYPES.ExportDefaultDeclaration
-                    ? statement.declaration
-                    : statement;
-                if (declaration?.type === utils_1.AST_NODE_TYPES.ClassDeclaration &&
+                const declaration = (0, lexicalScope_1.declarationOf)(statement);
+                if (declaration.type === utils_1.AST_NODE_TYPES.ClassDeclaration &&
                     declaration.id) {
                     classes.set(declaration.id.name, declaration.body);
                     continue;
                 }
-                if (declaration?.type === utils_1.AST_NODE_TYPES.VariableDeclaration) {
+                if (declaration.type === utils_1.AST_NODE_TYPES.VariableDeclaration) {
                     for (const declarator of declaration.declarations) {
                         if (declarator.id.type === utils_1.AST_NODE_TYPES.Identifier &&
                             declarator.init?.type === utils_1.AST_NODE_TYPES.ClassExpression) {
@@ -340,18 +315,7 @@ exports.enforceFirestoreSetMerge = (0, createRule_1.createRule)({
          * the shadow.
          */
         function resolveClassBody(name, reference) {
-            let current = reference;
-            while (current) {
-                const statements = statementsOf(current);
-                if (statements) {
-                    const found = containerClasses(current, statements).get(name);
-                    if (found) {
-                        return found;
-                    }
-                }
-                current = current.parent;
-            }
-            return null;
+            return ((0, lexicalScope_1.resolveInEnclosingScopes)(reference, (statements, container) => containerClasses(container, statements).get(name)) ?? null);
         }
         function enclosingClassBody(node) {
             let current = node.parent;

package/lib/rules/enforce-microdiff.js

@@ -37,6 +37,58 @@ const DIFF_FUNCTION_NAMES = new Set([
     'detailedDiff',
     // 'fastDeepEqual' and 'isEqual' stay out: they are allowed alternatives.
 ]);
+/**
+ * The names a hand-rolled comparison function is conventionally given. One
+ * shared set answers for both spellings of such a function — a `function`
+ * declaration and an arrow bound to a `const` — so neither can drift into
+ * recognising a name the other misses.
+ */
+const COMPARISON_FUNCTION_NAMES = new Set([
+    'detectChanges',
+    'hasConfigChanged',
+    'compareObjects',
+    'compareArrays',
+    'findChanges',
+    'detectDifferences',
+    'hasStateChanged',
+    'stateHasUpdated',
+    'arrayHasChanged',
+    'settingsChanged',
+]);
+/**
+ * The comparison function whose body the fix rewrites. A name alone does not
+ * fix what such a function returns — a boolean, the changed keys, the changes
+ * themselves — and a change list swapped in for the wrong one of those
+ * compiles, so the rest of the set is reported and left to its authors.
+ */
+const REWRITABLE_COMPARISON_NAME = 'hasConfigChanged';
+/**
+ * The markers that make a body look like a hand-rolled comparison. Text is
+ * enough to raise the report because the report says only that the body should
+ * be using microdiff; nothing is rewritten off these.
+ */
+function hasComparisonMarkers(bodyText) {
+    return (bodyText.includes('JSON.stringify') ||
+        bodyText.includes('Object.keys') ||
+        bodyText.includes('for (') ||
+        bodyText.includes('.some(') ||
+        bodyText.includes('.every('));
+}
+/**
+ * Whether a comparison function is one whose body the fix attempts. The gate is
+ * a text-level pre-filter over the name and the body: `collectStringifyComparisons`
+ * reads the AST afterwards and has the last word on whether a rewrite exists,
+ * so a body that clears this gate is still routinely left alone.
+ *
+ * The `!==` marker keeps the rewrite to bodies that phrase the question the way
+ * the name does — "has it changed?" — while an all-`===` body is reported and
+ * left for its author in either spelling.
+ */
+function isRewritableComparison(name, bodyText) {
+    return (name === REWRITABLE_COMPARISON_NAME &&
+        bodyText.includes('JSON.stringify') &&
+        bodyText.includes('!=='));
+}
 /**
  * The exports of a competing library whose call sites this rule rewrites,
  * whatever local name the import binds them to.
@@ -457,6 +509,62 @@ exports.enforceMicrodiff = (0, createRule_1.createRule)({
             const emptiness = comparison.isEqual ? '.length === 0' : '.length > 0';
             return `${DIFF_NAME}(${left}, ${right})${emptiness}`;
         }
+        /**
+         * The rewrite of a comparison function's body, or null when the body offers
+         * no single expression to replace or the emitted `diff` would not reach
+         * microdiff at `fn`.
+         *
+         * 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.
+         *
+         * 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.
+         *
+         * Replacing the comparison rather than the statement holding it is also what
+         * lets one implementation serve every spelling of the function: an arrow's
+         * concise expression body takes no `return` and no semicolon, and it needs
+         * none, because the text around the comparison is never part of the range.
+         */
+        function buildComparisonBodyFix(fixer, fn, body) {
+            const comparisons = collectStringifyComparisons(body);
+            if (comparisons.length !== 1 || !canEmitDiffAt(fn)) {
+                return null;
+            }
+            const bodyFix = fixer.replaceText(comparisons[0].node, buildDiffComparison(comparisons[0]));
+            const importFix = buildMicrodiffImportFix(fixer);
+            return importFix ? [importFix, bodyFix] : bodyFix;
+        }
+        /**
+         * Reports a hand-rolled comparison function, carrying the rewrite whenever
+         * its body offers one. Both spellings route through here so an identical
+         * violation is auto-remediable however it is written: a report with a fix in
+         * one spelling and without it in the other leaves the same code manual to
+         * resolve for no reason the author can see.
+         */
+        function reportComparisonFunction(node, name, body) {
+            const bodyText = sourceCode.getText(body);
+            if (isRewritableComparison(name, bodyText)) {
+                reportedNodes.add(node);
+                context.report({
+                    node,
+                    messageId: 'enforceMicrodiff',
+                    fix: (fixer) => buildComparisonBodyFix(fixer, node, body),
+                });
+                return;
+            }
+            if (hasComparisonMarkers(bodyText)) {
+                reportedNodes.add(node);
+                context.report({
+                    node,
+                    messageId: 'enforceMicrodiff',
+                });
+            }
+        }
         // 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
@@ -692,71 +800,14 @@ exports.enforceMicrodiff = (0, createRule_1.createRule)({
                 if (reportedNodes.has(node)) {
                     return;
                 }
-                // Look for functions that might be implementing diff logic
-                if (node.id &&
-                    [
-                        'detectChanges',
-                        'hasConfigChanged',
-                        'compareObjects',
-                        'compareArrays',
-                        'findChanges',
-                        'detectDifferences',
-                        'hasStateChanged',
-                        'stateHasUpdated',
-                        'arrayHasChanged',
-                        'settingsChanged',
-                    ].includes(node.id.name)) {
-                    // Check if function has two parameters that might be objects/arrays
-                    if (node.params.length >= 2) {
-                        const body = node.body;
-                        const bodyText = sourceCode.getText(body);
-                        // Check if the function body contains a JSON.stringify comparison
-                        if (node.id.name === 'hasConfigChanged' &&
-                            bodyText.includes('JSON.stringify') &&
-                            bodyText.includes('!==')) {
-                            reportedNodes.add(node);
-                            // 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 (!comparison || !canEmitDiffAt(node)) {
-                                        return null;
-                                    }
-                                    // 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;
-                                },
-                            });
-                            return;
-                        }
-                        // Look for patterns that suggest object/array comparison
-                        const hasComparisonLogic = bodyText.includes('JSON.stringify') ||
-                            bodyText.includes('Object.keys') ||
-                            bodyText.includes('for (') ||
-                            bodyText.includes('.some(') ||
-                            bodyText.includes('.every(');
-                        if (hasComparisonLogic) {
-                            reportedNodes.add(node);
-                            context.report({
-                                node,
-                                messageId: 'enforceMicrodiff',
-                            });
-                        }
-                    }
+                // Two parameters are what a comparison function needs, and what the
+                // `diff(a, b)` it is rewritten to needs as well.
+                if (!node.id ||
+                    !COMPARISON_FUNCTION_NAMES.has(node.id.name) ||
+                    node.params.length < 2) {
+                    return;
                 }
+                reportComparisonFunction(node, node.id.name, node.body);
             },
             // Check for custom deep comparison in arrow functions
             ArrowFunctionExpression(node) {
@@ -764,42 +815,17 @@ exports.enforceMicrodiff = (0, createRule_1.createRule)({
                 if (reportedNodes.has(node)) {
                     return;
                 }
-                // Only check arrow functions assigned to variables with comparison-like names
+                // The name an arrow answers to is the one its declarator binds, so an
+                // arrow passed straight to a call names nothing and is left alone.
                 const parent = node.parent;
-                if (parent &&
-                    parent.type === utils_1.AST_NODE_TYPES.VariableDeclarator &&
-                    parent.id.type === utils_1.AST_NODE_TYPES.Identifier &&
-                    [
-                        'detectChanges',
-                        'hasConfigChanged',
-                        'compareObjects',
-                        'compareArrays',
-                        'findChanges',
-                        'detectDifferences',
-                        'hasStateChanged',
-                        'stateHasUpdated',
-                        'arrayHasChanged',
-                        'settingsChanged',
-                    ].includes(parent.id.name)) {
-                    // Check if function has two parameters that might be objects/arrays
-                    if (node.params.length >= 2) {
-                        const body = node.body;
-                        // Look for patterns that suggest object/array comparison
-                        const bodyText = sourceCode.getText(body);
-                        const hasComparisonLogic = bodyText.includes('JSON.stringify') ||
-                            bodyText.includes('Object.keys') ||
-                            bodyText.includes('for (') ||
-                            bodyText.includes('.some(') ||
-                            bodyText.includes('.every(');
-                        if (hasComparisonLogic) {
-                            reportedNodes.add(node);
-                            context.report({
-                                node,
-                                messageId: 'enforceMicrodiff',
-                            });
-                        }
-                    }
+                if (!parent ||
+                    parent.type !== utils_1.AST_NODE_TYPES.VariableDeclarator ||
+                    parent.id.type !== utils_1.AST_NODE_TYPES.Identifier ||
+                    !COMPARISON_FUNCTION_NAMES.has(parent.id.name) ||
+                    node.params.length < 2) {
+                    return;
                 }
+                reportComparisonFunction(node, parent.id.name, node.body);
             },
         };
     },

package/lib/rules/no-direct-function-state.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.noDirectFunctionState = void 0;
 const utils_1 = require("@typescript-eslint/utils");
 const createRule_1 = require("../utils/createRule");
+const lexicalScope_1 = require("../utils/lexicalScope");
 const DEFAULT_FUNCTION_PATTERNS = [
     'callback',
     'handler',
@@ -10,20 +11,6 @@ const DEFAULT_FUNCTION_PATTERNS = [
     'func',
     'on[A-Z].*',
 ];
-/** Statement containers a type alias can be a direct child of. */
-function statementsOf(node) {
-    switch (node.type) {
-        case utils_1.AST_NODE_TYPES.Program:
-        case utils_1.AST_NODE_TYPES.BlockStatement:
-        case utils_1.AST_NODE_TYPES.TSModuleBlock:
-        case utils_1.AST_NODE_TYPES.StaticBlock:
-            return node.body;
-        case utils_1.AST_NODE_TYPES.SwitchCase:
-            return node.consequent;
-        default:
-            return undefined;
-    }
-}
 /**
  * The type alias a statement declares under `name`, looking through `export`.
  *
@@ -33,10 +20,7 @@ function statementsOf(node) {
  * readable, which says nothing about what the state holds.
  */
 function typeAliasNamed(statement, name) {
-    const declaration = statement.type === utils_1.AST_NODE_TYPES.ExportNamedDeclaration &&
-        statement.declaration
-        ? statement.declaration
-        : statement;
+    const declaration = (0, lexicalScope_1.declarationOf)(statement);
     return declaration.type === utils_1.AST_NODE_TYPES.TSTypeAliasDeclaration &&
         declaration.id.name === name
         ? declaration
@@ -56,20 +40,15 @@ function typeAliasNamed(statement, name) {
  * hoisting of type declarations.
  */
 function resolveTypeAlias(from, name) {
-    let current = from;
-    while (current) {
-        const statements = statementsOf(current);
-        if (statements) {
-            for (const statement of statements) {
-                const alias = typeAliasNamed(statement, name);
-                if (alias) {
-                    return alias;
-                }
+    return (0, lexicalScope_1.resolveInEnclosingScopes)(from, (statements) => {
+        for (const statement of statements) {
+            const alias = typeAliasNamed(statement, name);
+            if (alias) {
+                return alias;
             }
         }
-        current = current.parent;
-    }
-    return undefined;
+        return undefined;
+    });
 }
 /**
  * Returns true if the TSTypeAnnotation node (from useState's type parameter)

package/lib/rules/no-explicit-return-type.js

@@ -5,6 +5,7 @@ const utils_1 = require("@typescript-eslint/utils");
 const createRule_1 = require("../utils/createRule");
 const disableDirectives_1 = require("../utils/disableDirectives");
 const importRemoval_1 = require("../utils/importRemoval");
+const lexicalScope_1 = require("../utils/lexicalScope");
 const defaultOptions = {
     allowRecursiveFunctions: true,
     allowOverloadedFunctions: true,
@@ -401,24 +402,6 @@ function collectReturnIdentifierNames(fn, visitorKeys) {
     }
     return names;
 }
-/**
- * The statement list a container holds, or undefined for a node that holds
- * none. These are every place a function can be declared as a direct child, so
- * walking them outward reproduces TypeScript's own scope chain.
- */
-function statementsOf(node) {
-    switch (node.type) {
-        case utils_1.AST_NODE_TYPES.Program:
-        case utils_1.AST_NODE_TYPES.BlockStatement:
-        case utils_1.AST_NODE_TYPES.TSModuleBlock:
-        case utils_1.AST_NODE_TYPES.StaticBlock:
-            return node.body;
-        case utils_1.AST_NODE_TYPES.SwitchCase:
-            return node.consequent;
-        default:
-            return undefined;
-    }
-}
 /**
  * What a statement list binds each of its names to: the function when the name
  * denotes one, `null` when it denotes anything else.
@@ -437,11 +420,7 @@ function scopeBindings(statements) {
     for (const rawStatement of statements) {
         // `export function f() {}` is the same declaration one AST node deeper, and
         // the `export` keyword alone cannot decide whether a name is resolvable.
-        const statement = (rawStatement.type === utils_1.AST_NODE_TYPES.ExportNamedDeclaration ||
-            rawStatement.type === utils_1.AST_NODE_TYPES.ExportDefaultDeclaration) &&
-            rawStatement.declaration
-            ? rawStatement.declaration
-            : rawStatement;
+        const statement = (0, lexicalScope_1.declarationOf)(rawStatement);
         if (statement.type === utils_1.AST_NODE_TYPES.FunctionDeclaration && statement.id) {
             bind(statement.id.name, statement.body ? statement : null);
             continue;
@@ -510,20 +489,14 @@ function createReturnCycleResolver(visitorKeys) {
         bindings.set(container, computed);
         return computed;
     };
-    const resolveFunctionInScope = (from, name) => {
-        let current = from;
-        while (current) {
-            const statements = statementsOf(current);
-            if (statements) {
-                const scope = bindingsOf(current, statements);
-                if (scope.has(name)) {
-                    return scope.get(name) ?? undefined;
-                }
-            }
-            current = current.parent;
-        }
-        return undefined;
-    };
+    const resolveFunctionInScope = (from, name) => (0, lexicalScope_1.resolveInEnclosingScopes)(from, (statements, container) => {
+        const scope = bindingsOf(container, statements);
+        if (!scope.has(name))
+            return undefined;
+        // A non-function binding still shadows a same-named outer function, so
+        // it ends the search without yielding one.
+        return scope.get(name) ?? lexicalScope_1.BOUND_UNPROVABLE;
+    });
     const edgesOf = (fn) => {
         const cached = edges.get(fn);
         if (cached)