@blumintinc/eslint-plugin-blumint 1.20.8 → 1.20.10

package/lib/rules/enforce-snapshot-state-narrowing.js

@@ -9,7 +9,37 @@ const DEFAULT_SNAPSHOT_HOOKS = [
     'useCachedDocSnapshot',
     'useFirestore',
 ];
-const DEFAULT_GUARD_FUNCTIONS = ['isSnapshotReady'];
+const GUARD_NAME = 'isSnapshotReady';
+const DEFAULT_GUARD_FUNCTIONS = [GUARD_NAME];
+/**
+ * Where the canonical guard lives. The rule's own default `excludeFiles` entry
+ * names the guard's implementation file, so the fixer writes an import for that
+ * very module rather than guessing a path.
+ */
+const DEFAULT_GUARD_IMPORT_SOURCE = 'src/types/FirestoreSnapshotState';
+/**
+ * Parents that accept a bare conditional expression without parentheses. Any
+ * other parent binds tighter than `?:` (or reads ambiguously next to it), so the
+ * rewritten expression is wrapped.
+ */
+const PARENTHESES_FREE_PARENTS = new Set([
+    utils_1.AST_NODE_TYPES.ArrayExpression,
+    utils_1.AST_NODE_TYPES.ArrowFunctionExpression,
+    utils_1.AST_NODE_TYPES.AssignmentExpression,
+    utils_1.AST_NODE_TYPES.AssignmentPattern,
+    utils_1.AST_NODE_TYPES.DoWhileStatement,
+    utils_1.AST_NODE_TYPES.ExpressionStatement,
+    utils_1.AST_NODE_TYPES.ForStatement,
+    utils_1.AST_NODE_TYPES.IfStatement,
+    utils_1.AST_NODE_TYPES.JSXExpressionContainer,
+    utils_1.AST_NODE_TYPES.Property,
+    utils_1.AST_NODE_TYPES.ReturnStatement,
+    utils_1.AST_NODE_TYPES.SwitchCase,
+    utils_1.AST_NODE_TYPES.SwitchStatement,
+    utils_1.AST_NODE_TYPES.ThrowStatement,
+    utils_1.AST_NODE_TYPES.VariableDeclarator,
+    utils_1.AST_NODE_TYPES.WhileStatement,
+]);
 exports.enforceSnapshotStateNarrowing = (0, createRule_1.createRule)({
     name: 'enforce-snapshot-state-narrowing',
     meta: {
@@ -38,6 +68,10 @@ exports.enforceSnapshotStateNarrowing = (0, createRule_1.createRule)({
                         items: { type: 'string' },
                         description: 'File patterns to exclude from this rule',
                     },
+                    guardImportSource: {
+                        type: 'string',
+                        description: 'Module specifier the suggestion imports isSnapshotReady from',
+                    },
                 },
                 additionalProperties: false,
             },
@@ -56,6 +90,7 @@ exports.enforceSnapshotStateNarrowing = (0, createRule_1.createRule)({
         const excludeFiles = options?.excludeFiles ?? [
             'src/types/FirestoreSnapshotState.ts',
         ];
+        const guardImportSource = options?.guardImportSource ?? DEFAULT_GUARD_IMPORT_SOURCE;
         // Check if the current file should be excluded
         const filename = context.getFilename();
         if (excludeFiles.some((pattern) => filename.endsWith(pattern))) {
@@ -98,6 +133,149 @@ exports.enforceSnapshotStateNarrowing = (0, createRule_1.createRule)({
                 return '<expression>';
             }
         }
+        /**
+         * Strips a module specifier down to its final segment so an import written
+         * as a relative path, an alias, or with an extension is still recognized as
+         * the guard's module.
+         */
+        function moduleBasename(source) {
+            const withoutExtension = source.replace(/\.[cm]?[jt]sx?$/, '');
+            const segments = withoutExtension.split('/');
+            return segments[segments.length - 1];
+        }
+        const guardModuleName = moduleBasename(guardImportSource);
+        function isGuardModule(source) {
+            return (source === guardImportSource ||
+                moduleBasename(source) === guardModuleName);
+        }
+        function importDeclarationsOf() {
+            return context
+                .getSourceCode()
+                .ast.body.filter((statement) => statement.type === utils_1.AST_NODE_TYPES.ImportDeclaration &&
+                typeof statement.source.value === 'string');
+        }
+        function isValueImportSpecifier(specifier) {
+            return (specifier.type === utils_1.AST_NODE_TYPES.ImportSpecifier &&
+                specifier.importKind !== 'type');
+        }
+        /**
+         * Decides whether the emitted guard call resolves as written, needs an
+         * import, or would collide with an unrelated binding of the same name.
+         */
+        function resolveGuardBinding(scope) {
+            const variable = utils_1.ASTUtils.findVariable(scope, GUARD_NAME);
+            if (!variable) {
+                return 'missing';
+            }
+            const [definition] = variable.defs;
+            if (!definition) {
+                return 'conflict';
+            }
+            const definitionNode = definition.node;
+            if (definitionNode.type === utils_1.AST_NODE_TYPES.ImportSpecifier ||
+                definitionNode.type === utils_1.AST_NODE_TYPES.ImportDefaultSpecifier) {
+                // A type-only binding is erased at runtime, so calling it is not an
+                // option — importing the value would then clash with the type binding.
+                if (definitionNode.type === utils_1.AST_NODE_TYPES.ImportSpecifier &&
+                    definitionNode.importKind === 'type') {
+                    return 'conflict';
+                }
+                const declaration = definitionNode.parent;
+                if (!declaration ||
+                    declaration.type !== utils_1.AST_NODE_TYPES.ImportDeclaration ||
+                    declaration.importKind === 'type') {
+                    return 'conflict';
+                }
+                // Any value import under this name reaches the guard (a barrel or
+                // re-export is still the same function), so no second import is needed.
+                return 'bound';
+            }
+            // A file that declares the guard itself already has a callable binding.
+            if (definitionNode.type === utils_1.AST_NODE_TYPES.FunctionDeclaration) {
+                return 'bound';
+            }
+            if (definitionNode.type === utils_1.AST_NODE_TYPES.VariableDeclarator &&
+                (definitionNode.init?.type === utils_1.AST_NODE_TYPES.ArrowFunctionExpression ||
+                    definitionNode.init?.type === utils_1.AST_NODE_TYPES.FunctionExpression)) {
+                return 'bound';
+            }
+            return 'conflict';
+        }
+        /**
+         * Makes the emitted guard call resolve: extend an existing import of the
+         * guard's module when there is one to extend (reusing that file's own path),
+         * otherwise add the canonical import statement.
+         */
+        function buildImportFix(fixer) {
+            const declarations = importDeclarationsOf();
+            const guardDeclarations = declarations.filter((declaration) => isGuardModule(String(declaration.source.value)));
+            const reusable = guardDeclarations.find((declaration) => declaration.importKind !== 'type' &&
+                declaration.specifiers.some(isValueImportSpecifier));
+            if (reusable) {
+                const namedSpecifiers = reusable.specifiers.filter(isValueImportSpecifier);
+                const lastSpecifier = namedSpecifiers[namedSpecifiers.length - 1];
+                return fixer.insertTextAfter(lastSpecifier, `, ${GUARD_NAME}`);
+            }
+            // A namespace or type-only import of the module cannot take a named value
+            // specifier, but its path is proof of how this file reaches the module.
+            const source = guardDeclarations.length
+                ? String(guardDeclarations[0].source.value)
+                : guardImportSource;
+            const importText = `import { ${GUARD_NAME} } from '${source}';\n`;
+            const [firstImport] = declarations;
+            if (firstImport) {
+                return fixer.insertTextBefore(firstImport, importText);
+            }
+            // Keep the import visually separated from the code it precedes unless the
+            // file already opens with a blank line.
+            const separator = /^\r?\n/.test(context.getSourceCode().text) ? '' : '\n';
+            return fixer.insertTextBeforeRange([0, 0], `${importText}${separator}`);
+        }
+        /**
+         * Builds the single suggestion shared by every report: swap the flagged
+         * expression for its guard-based equivalent and bring `isSnapshotReady` into
+         * scope. Declines (no suggestion) when the name is already taken by
+         * something that is not the guard.
+         */
+        function guardSuggestion(messageId, fixNode, replacement, scope) {
+            return [
+                {
+                    messageId,
+                    data: { expression: replacement },
+                    fix(fixer) {
+                        const binding = resolveGuardBinding(scope);
+                        if (binding === 'conflict') {
+                            return null;
+                        }
+                        const fixes = [fixer.replaceText(fixNode, replacement)];
+                        if (binding === 'missing') {
+                            fixes.unshift(buildImportFix(fixer));
+                        }
+                        return fixes;
+                    },
+                },
+            ];
+        }
+        /**
+         * True when a conditional expression substituted for `node` would need
+         * parentheses to preserve the surrounding expression's grouping.
+         */
+        function needsParentheses(node) {
+            // Source parentheses live outside the replaced range, so they already do
+            // the grouping and a second pair would only add noise.
+            if (utils_1.ASTUtils.isParenthesized(node, context.getSourceCode())) {
+                return false;
+            }
+            const parent = node.parent;
+            if (!parent) {
+                return true;
+            }
+            if (parent.type === utils_1.AST_NODE_TYPES.CallExpression ||
+                parent.type === utils_1.AST_NODE_TYPES.NewExpression) {
+                return parent.callee === node;
+            }
+            return !PARENTHESES_FREE_PARENTS.has(parent.type);
+        }
         /**
          * Checks a BinaryExpression for raw typeof narrowing patterns that attempt
          * to narrow the state to data:
@@ -120,42 +298,16 @@ exports.enforceSnapshotStateNarrowing = (0, createRule_1.createRule)({
                 const literal = right.value;
                 if (operand.type === utils_1.AST_NODE_TYPES.Identifier &&
                     isSnapshotVar(operand)) {
-                    // typeof state === 'object' — bad: narrows to data, use isSnapshotReady
-                    if (operator === '===' && literal === 'object') {
-                        context.report({
-                            node,
-                            messageId: 'noRawTypeof',
-                            data: { expression: getText(node) },
-                            suggest: [
-                                {
-                                    messageId: 'noRawTypeof',
-                                    data: {
-                                        expression: `isSnapshotReady(${operand.name})`,
-                                    },
-                                    fix(fixer) {
-                                        return fixer.replaceText(node, `isSnapshotReady(${operand.name})`);
-                                    },
-                                },
-                            ],
-                        });
-                    }
-                    // typeof state !== 'string' — bad: equivalent to isSnapshotReady
-                    else if (operator === '!==' && literal === 'string') {
+                    // Both flagged forms are true exactly when the state holds data, so
+                    // the guard replaces them with matching polarity.
+                    const isToDataCheck = (operator === '===' && literal === 'object') ||
+                        (operator === '!==' && literal === 'string');
+                    if (isToDataCheck) {
                         context.report({
                             node,
                             messageId: 'noRawTypeof',
                             data: { expression: getText(node) },
-                            suggest: [
-                                {
-                                    messageId: 'noRawTypeof',
-                                    data: {
-                                        expression: `isSnapshotReady(${operand.name})`,
-                                    },
-                                    fix(fixer) {
-                                        return fixer.replaceText(node, `isSnapshotReady(${operand.name})`);
-                                    },
-                                },
-                            ],
+                            suggest: guardSuggestion('noRawTypeof', node, `${GUARD_NAME}(${operand.name})`, context.getScope()),
                         });
                     }
                     // typeof state === 'string' — allowed (narrows to non-data states)
@@ -165,22 +317,18 @@ exports.enforceSnapshotStateNarrowing = (0, createRule_1.createRule)({
         }
         /**
          * Reports a falsy/truthy check on a snapshot-state identifier.
+         *
+         * `replacement` must match the polarity of the flagged expression: a falsy
+         * check reads `!isSnapshotReady(state)`, a truthy one `isSnapshotReady(state)`.
+         * `fixNode` defaults to the reported node but can be widened when the whole
+         * surrounding expression has to be rewritten (e.g. `state || fallback`).
          */
-        function reportFalsyCheck(node, expression, varName) {
+        function reportFalsyCheck(node, expression, replacement, fixNode = node) {
             context.report({
                 node,
                 messageId: 'noFalsyCheck',
                 data: { expression },
-                suggest: [
-                    {
-                        messageId: 'noFalsyCheck',
-                        data: { expression: `isSnapshotReady(${varName})` },
-                        fix(fixer) {
-                            // Replace the entire flagged expression with the canonical guard
-                            return fixer.replaceText(node, `isSnapshotReady(${varName})`);
-                        },
-                    },
-                ],
+                suggest: guardSuggestion('noFalsyCheck', fixNode, replacement, context.getScope()),
             });
         }
         return {
@@ -219,19 +367,21 @@ exports.enforceSnapshotStateNarrowing = (0, createRule_1.createRule)({
                     return;
                 }
                 const argument = node.argument;
-                // !state — the argument is directly the snapshot var
+                // !state — the argument is directly the snapshot var.
+                // The check is true when the state is NOT usable, so the guard has to
+                // stay negated or the suggestion would reverse the control flow.
                 if (argument.type === utils_1.AST_NODE_TYPES.Identifier &&
                     isSnapshotVar(argument)) {
-                    const expression = `!${argument.name}`;
-                    reportFalsyCheck(node, expression, argument.name);
+                    reportFalsyCheck(node, `!${argument.name}`, `!${GUARD_NAME}(${argument.name})`);
                 }
-                // !!state — the argument is another `!` whose argument is the snapshot var
+                // !!state — the argument is another `!` whose argument is the snapshot var.
+                // The double negation is a truthiness coercion, so the guard is positive.
                 else if (argument.type === utils_1.AST_NODE_TYPES.UnaryExpression &&
                     argument.operator === '!' &&
                     argument.argument.type === utils_1.AST_NODE_TYPES.Identifier &&
                     isSnapshotVar(argument.argument)) {
                     const varName = argument.argument.name;
-                    reportFalsyCheck(node, `!!${varName}`, varName);
+                    reportFalsyCheck(node, `!!${varName}`, `${GUARD_NAME}(${varName})`);
                 }
             },
             // IfStatement: if (state) { ... } or if (!state) { ... }
@@ -239,14 +389,14 @@ exports.enforceSnapshotStateNarrowing = (0, createRule_1.createRule)({
             IfStatement(node) {
                 const test = node.test;
                 if (test.type === utils_1.AST_NODE_TYPES.Identifier && isSnapshotVar(test)) {
-                    reportFalsyCheck(test, test.name, test.name);
+                    reportFalsyCheck(test, test.name, `${GUARD_NAME}(${test.name})`);
                 }
             },
             // ConditionalExpression: state ? a : b
             ConditionalExpression(node) {
                 const test = node.test;
                 if (test.type === utils_1.AST_NODE_TYPES.Identifier && isSnapshotVar(test)) {
-                    reportFalsyCheck(test, test.name, test.name);
+                    reportFalsyCheck(test, test.name, `${GUARD_NAME}(${test.name})`);
                 }
             },
             // LogicalExpression: state && expr, state || expr
@@ -255,7 +405,17 @@ exports.enforceSnapshotStateNarrowing = (0, createRule_1.createRule)({
                 if ((node.operator === '&&' || node.operator === '||') &&
                     left.type === utils_1.AST_NODE_TYPES.Identifier &&
                     isSnapshotVar(left)) {
-                    reportFalsyCheck(left, left.name, left.name);
+                    if (node.operator === '&&') {
+                        // `state && expr` guards expr, so swapping the operand for the
+                        // guard keeps both the polarity and the narrowing of `state`.
+                        reportFalsyCheck(left, left.name, `${GUARD_NAME}(${left.name})`);
+                        return;
+                    }
+                    // `state || fallback` evaluates to the state itself when it is
+                    // usable, so a bare operand swap would yield `true` instead of the
+                    // data. Only the conditional form preserves that value.
+                    const guarded = `${GUARD_NAME}(${left.name}) ? ${left.name} : ${getText(node.right)}`;
+                    reportFalsyCheck(left, left.name, needsParentheses(node) ? `(${guarded})` : guarded, node);
                 }
             },
             // BinaryExpression: typeof state === 'object', typeof state !== 'string'
@@ -272,7 +432,7 @@ exports.enforceSnapshotStateNarrowing = (0, createRule_1.createRule)({
                     node.arguments[0].type === utils_1.AST_NODE_TYPES.Identifier &&
                     isSnapshotVar(node.arguments[0])) {
                     const varName = node.arguments[0].name;
-                    reportFalsyCheck(node, `Boolean(${varName})`, varName);
+                    reportFalsyCheck(node, `Boolean(${varName})`, `${GUARD_NAME}(${varName})`);
                 }
             },
         };

package/lib/rules/no-class-instance-destructuring.js

@@ -101,6 +101,13 @@ exports.noClassInstanceDestructuring = (0, createRule_1.createRule)({
                             // Skip if there's no init expression
                             if (!node.init)
                                 return null;
+                            // An annotation on the pattern types the object as a whole, not
+                            // each property, so it cannot be split across the per-property
+                            // declarations this fixer emits. Deriving per-property types needs
+                            // the type checker, so report without fixing rather than rewrite
+                            // the code to something more weakly typed than the author wrote.
+                            if (objectPattern.typeAnnotation)
+                                return null;
                             // For single property, use simple replacement
                             if (properties.length === 1) {
                                 const prop = properties[0];

package/lib/rules/no-excessive-parent-chain.js

@@ -54,6 +54,36 @@ exports.noExcessiveParentChain = (0, createRule_1.createRule)({
             }
             return current.type === utils_1.AST_NODE_TYPES.Identifier ? current.name : null;
         };
+        // Suggestions rewrite the chain as `<event>.params`, so the event binding has
+        // to be resolved back to a real identifier. Handler parameters destructured
+        // in place (`async ({ data: change }) => ...`) have no such identifier and
+        // resolve to null so the report can decline to suggest rather than guess.
+        const resolveEventParamName = (rootIdentifier) => {
+            if (eventIdentifiers.has(rootIdentifier) &&
+                rootIdentifier !== HANDLER_PARAM_SOURCE) {
+                return rootIdentifier;
+            }
+            const source = eventDataVariables.get(rootIdentifier);
+            if (!source || source === HANDLER_PARAM_SOURCE) {
+                return null;
+            }
+            return source;
+        };
+        // Every hop of a chain is reported separately, so an inner report's fix must
+        // still span the outermost hop. Replacing only the reported slice leaves a
+        // dangling hop behind (for example `event.params.parent.id`).
+        const getOutermostParentHop = (node) => {
+            let outermost = node;
+            let ancestor = outermost.parent;
+            while (ancestor?.type === utils_1.AST_NODE_TYPES.MemberExpression &&
+                ancestor.object === outermost &&
+                ancestor.property.type === utils_1.AST_NODE_TYPES.Identifier &&
+                ancestor.property.name === 'parent') {
+                outermost = ancestor;
+                ancestor = outermost.parent;
+            }
+            return outermost;
+        };
         const hasRefProperty = (node) => {
             let current = node;
             while (current) {
@@ -251,23 +281,26 @@ exports.noExcessiveParentChain = (0, createRule_1.createRule)({
                         !eventIdentifiers.has(rootIdentifier))) {
                     return;
                 }
+                const eventParamName = resolveEventParamName(rootIdentifier);
                 context.report({
                     node,
                     messageId: 'excessiveParentChain',
                     data: {
                         count: parentCount,
                     },
-                    suggest: [
-                        {
-                            messageId: 'excessiveParentChain',
-                            data: {
-                                count: parentCount,
-                            },
-                            fix(fixer) {
-                                return fixer.replaceText(node, 'event.params');
+                    suggest: eventParamName
+                        ? [
+                            {
+                                messageId: 'excessiveParentChain',
+                                data: {
+                                    count: parentCount,
+                                },
+                                fix(fixer) {
+                                    return fixer.replaceText(getOutermostParentHop(node), `${eventParamName}.params`);
+                                },
                             },
-                        },
-                    ],
+                        ]
+                        : [],
                 });
             },
         };

package/lib/rules/no-unnecessary-destructuring.js

@@ -43,8 +43,15 @@ exports.noUnnecessaryDestructuring = (0, createRule_1.createRule)({
                                 return null;
                             }
                             const initText = sourceCode.getText(node.init);
+                            // The declarator's range covers `node.id.typeAnnotation`, so
+                            // replacing the whole declarator would silently drop it. A lone
+                            // rest element binds the entire object, meaning the annotation
+                            // describes the new binding exactly and can be re-emitted as-is.
+                            const annotationText = node.id.typeAnnotation
+                                ? sourceCode.getText(node.id.typeAnnotation)
+                                : '';
                             // Replace the destructuring with direct assignment
-                            return fixer.replaceText(node, `${restName} = ${initText}`);
+                            return fixer.replaceText(node, `${restName}${annotationText} = ${initText}`);
                         },
                     });
                 }

package/lib/rules/prefer-clone-deep.d.ts

@@ -1 +1,2 @@
-export declare const preferCloneDeep: import("@typescript-eslint/utils/dist/ts-eslint/Rule").RuleModule<"preferCloneDeep", [], import("@typescript-eslint/utils/dist/ts-eslint/Rule").RuleListener>;
+import { TSESLint } from '@typescript-eslint/utils';
+export declare const preferCloneDeep: TSESLint.RuleModule<"preferCloneDeep", [], TSESLint.RuleListener>;