@blumintinc/eslint-plugin-blumint 1.20.137 → 1.20.139

package/lib/index.js

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

package/lib/rules/enforce-assert-safe-object-key.js

@@ -304,6 +304,15 @@ function templateCanSpell(quasis, target) {
     }
     return true;
 }
+/**
+ * A `: number` type annotation. Every declaration site spells the proof with
+ * the same `TSTypeAnnotation` wrapper — a binding name, a class property, a
+ * function's return type — so one predicate reads them all, and which site the
+ * author chose stops deciding the verdict.
+ */
+function isNumberTypeAnnotation(annotation) {
+    return annotation?.typeAnnotation.type === utils_1.AST_NODE_TYPES.TSNumberKeyword;
+}
 /**
  * A `: number` annotation on a binding name. Parameters and variable
  * declarators are the bindings that carry one, and TypeScript checks every
@@ -311,7 +320,171 @@ function templateCanSpell(quasis, target) {
  */
 function isNumberAnnotated(node) {
     return (node.type === utils_1.AST_NODE_TYPES.Identifier &&
-        node.typeAnnotation?.typeAnnotation.type === utils_1.AST_NODE_TYPES.TSNumberKeyword);
+        isNumberTypeAnnotation(node.typeAnnotation));
+}
+/** The node read as a function, or null when it is not one. */
+function asFunctionNode(node) {
+    switch (node.type) {
+        case utils_1.AST_NODE_TYPES.FunctionDeclaration:
+        case utils_1.AST_NODE_TYPES.FunctionExpression:
+        case utils_1.AST_NODE_TYPES.ArrowFunctionExpression:
+        case utils_1.AST_NODE_TYPES.TSDeclareFunction:
+        case utils_1.AST_NODE_TYPES.TSEmptyBodyFunctionExpression:
+            return node;
+        default:
+            return null;
+    }
+}
+/**
+ * Whether a function declares that it returns a number. The `: number` on a
+ * return type is the author's own claim at a declaration site, and TypeScript
+ * rejects every `return` that contradicts it — the same trust a `: number`
+ * binding annotation already earns, spelled one node over.
+ *
+ * A laundering assertion inside the body (`return raw as unknown as number`)
+ * switches that check off for the one statement carrying it, and is still
+ * credited here. `const k: number = raw as unknown as number` is credited for
+ * exactly the same reason: the annotation, not the initializer, is what the
+ * proof rests on. Refusing the return annotation alone would reinstate the very
+ * asymmetry between declaration sites this predicate exists to remove — and a
+ * body scan is not a proof anyway, since the laundering can happen one call or
+ * one local alias further away and read as clean.
+ */
+function returnsNumberType(node) {
+    const fn = asFunctionNode(node);
+    return !!fn && isNumberTypeAnnotation(fn.returnType);
+}
+/** The binding a constructor parameter property declares, default and all. */
+function parameterPropertyBinding(node) {
+    return node.parameter.type === utils_1.AST_NODE_TYPES.AssignmentPattern
+        ? node.parameter.left
+        : node.parameter;
+}
+/** Class members that declare a value under a name of their own. */
+const NAMED_CLASS_MEMBER_TYPES = new Set([
+    utils_1.AST_NODE_TYPES.MethodDefinition,
+    utils_1.AST_NODE_TYPES.TSAbstractMethodDefinition,
+    utils_1.AST_NODE_TYPES.PropertyDefinition,
+    utils_1.AST_NODE_TYPES.TSAbstractPropertyDefinition,
+    utils_1.AST_NODE_TYPES.AccessorProperty,
+    utils_1.AST_NODE_TYPES.TSAbstractAccessorProperty,
+]);
+/**
+ * The name a class member declares, or null for an index signature, a static
+ * block, or a computed key whose text names no member the syntax can match.
+ */
+function classMemberName(member) {
+    if (!NAMED_CLASS_MEMBER_TYPES.has(member.type)) {
+        return null;
+    }
+    const { key, computed } = member;
+    if (computed) {
+        return null;
+    }
+    if (key.type === utils_1.AST_NODE_TYPES.Identifier) {
+        return key.name;
+    }
+    return key.type === utils_1.AST_NODE_TYPES.Literal && typeof key.value === 'string'
+        ? key.value
+        : null;
+}
+/**
+ * A setter declares what a write to the member accepts, never what a read of it
+ * yields — a `get depth(): number` paired with a `set depth(v: string)` reads
+ * as a number. So the setter is left out of the judgement rather than failing
+ * it, which would let adding a setter re-report the getter's own proof.
+ */
+function isSetterDeclaration(node) {
+    return ((node.type === utils_1.AST_NODE_TYPES.MethodDefinition ||
+        node.type === utils_1.AST_NODE_TYPES.TSAbstractMethodDefinition) &&
+        node.kind === 'set');
+}
+/**
+ * Whether reading the member yields a number by its own declaration: a property
+ * annotated `: number`, a getter returning `: number`, or a constructor
+ * parameter property annotated `: number`.
+ */
+function memberReadsNumber(declaration) {
+    switch (declaration.type) {
+        case utils_1.AST_NODE_TYPES.PropertyDefinition:
+        case utils_1.AST_NODE_TYPES.TSAbstractPropertyDefinition:
+        case utils_1.AST_NODE_TYPES.AccessorProperty:
+        case utils_1.AST_NODE_TYPES.TSAbstractAccessorProperty:
+            return isNumberTypeAnnotation(declaration.typeAnnotation);
+        case utils_1.AST_NODE_TYPES.MethodDefinition:
+        case utils_1.AST_NODE_TYPES.TSAbstractMethodDefinition:
+            return declaration.kind === 'get' && returnsNumberType(declaration.value);
+        case utils_1.AST_NODE_TYPES.TSParameterProperty:
+            return isNumberAnnotated(parameterPropertyBinding(declaration));
+        default:
+            return false;
+    }
+}
+/** Whether calling the member returns a number by its own declaration. */
+function memberCallReturnsNumber(declaration) {
+    switch (declaration.type) {
+        case utils_1.AST_NODE_TYPES.MethodDefinition:
+        case utils_1.AST_NODE_TYPES.TSAbstractMethodDefinition:
+            return (declaration.kind === 'method' && returnsNumberType(declaration.value));
+        case utils_1.AST_NODE_TYPES.PropertyDefinition:
+        case utils_1.AST_NODE_TYPES.TSAbstractPropertyDefinition:
+        case utils_1.AST_NODE_TYPES.AccessorProperty:
+        case utils_1.AST_NODE_TYPES.TSAbstractAccessorProperty:
+            return !!declaration.value && returnsNumberType(declaration.value);
+        default:
+            return false;
+    }
+}
+/**
+ * Whether the function is the body of a class member rather than a function of
+ * its own. A method's `FunctionExpression` receives the class instance as
+ * `this`; every other non-arrow function receives its own call-time receiver.
+ */
+function isClassMemberBody(node) {
+    const owner = node.parent;
+    switch (owner?.type) {
+        case utils_1.AST_NODE_TYPES.MethodDefinition:
+        case utils_1.AST_NODE_TYPES.TSAbstractMethodDefinition:
+        case utils_1.AST_NODE_TYPES.PropertyDefinition:
+        case utils_1.AST_NODE_TYPES.TSAbstractPropertyDefinition:
+        case utils_1.AST_NODE_TYPES.AccessorProperty:
+        case utils_1.AST_NODE_TYPES.TSAbstractAccessorProperty:
+            return owner.value === node;
+        default:
+            return false;
+    }
+}
+/**
+ * The half of a class — static or instance — that `this` reaches at a node,
+ * together with the body whose members it names. A non-arrow function rebinds
+ * `this` to its own call-time receiver, so the walk stops there unless that
+ * function IS a member's body; an arrow keeps the enclosing `this`, which is
+ * what makes `read = () => this.rank` resolve against the class it is written
+ * in. The walk stops at the innermost class body, so a nested class shadows the
+ * outer one exactly as `this` does at run time.
+ */
+function enclosingClassContext(node) {
+    let child = node;
+    let parent = node.parent;
+    while (parent) {
+        if (parent.type === utils_1.AST_NODE_TYPES.ClassBody) {
+            // A static block's `this` is the class object, the same half of the class
+            // a `static` member lives on.
+            return {
+                body: parent,
+                isStatic: child.type === utils_1.AST_NODE_TYPES.StaticBlock ||
+                    child.static === true,
+            };
+        }
+        if ((parent.type === utils_1.AST_NODE_TYPES.FunctionExpression ||
+            parent.type === utils_1.AST_NODE_TYPES.FunctionDeclaration) &&
+            !isClassMemberBody(parent)) {
+            return null;
+        }
+        child = parent;
+        parent = parent.parent;
+    }
+    return null;
 }
 /** The types an assertion can launder any value through without complaint. */
 const LAUNDERING_ASSERTION_TYPES = new Set([
@@ -993,6 +1166,140 @@ exports.enforceAssertSafeObjectKey = (0, createRule_1.createRule)({
             }
             return keyAnnotations.every((keyAnnotation) => recordKeyTypes.every((recordKeyType) => recordKeyCovers(keyAnnotation, recordKeyType, node)));
         };
+        /**
+         * The class body an identifier names. A class reached by its own name
+         * exposes only the static half of itself, which is why the caller is told
+         * so rather than left to guess.
+         */
+        const classBodyOfName = (identifier) => {
+            const variable = ASTHelpers_1.ASTHelpers.findVariableInScope(ASTHelpers_1.ASTHelpers.getScope(context, identifier), identifier.name);
+            if (!variable || variable.defs.length !== 1) {
+                return null;
+            }
+            const { node: definition } = variable.defs[0];
+            if (definition.type === utils_1.AST_NODE_TYPES.ClassDeclaration) {
+                return definition.body;
+            }
+            return definition.type === utils_1.AST_NODE_TYPES.VariableDeclarator &&
+                definition.init?.type === utils_1.AST_NODE_TYPES.ClassExpression
+                ? definition.init.body
+                : null;
+        };
+        /**
+         * The class body a receiver's members are declared in, and which half of it
+         * the receiver reaches. `this` resolves to the class it is written in;
+         * a bare name resolves to the class that name binds to, whose members it
+         * reaches statically. Anything else — a parameter, an import, a `super`
+         * whose class may live in another file — resolves to no body, so the
+         * annotation on a same-named member of some other class is never read.
+         */
+        const receiverClassContext = (receiver) => {
+            const target = unwrapWrittenKey(receiver);
+            if (target.type === utils_1.AST_NODE_TYPES.ThisExpression) {
+                return enclosingClassContext(target);
+            }
+            if (target.type !== utils_1.AST_NODE_TYPES.Identifier) {
+                return null;
+            }
+            const body = classBodyOfName(target);
+            return body ? { body, isStatic: true } : null;
+        };
+        /**
+         * The declarations of a member name on one half of a class. A `static`
+         * member and an instance member of the same name are separate declarations
+         * that TypeScript keeps apart, so crediting the wrong half would credit an
+         * annotation the reference does not resolve to. Constructor parameter
+         * properties declare a member too, and are read alongside the body's own
+         * elements.
+         */
+        const classMemberDeclarations = (body, name, isStatic) => {
+            const declarations = [];
+            for (const member of body.body) {
+                if (!isStatic &&
+                    member.type === utils_1.AST_NODE_TYPES.MethodDefinition &&
+                    member.kind === 'constructor') {
+                    for (const parameter of member.value.params) {
+                        if (parameter.type === utils_1.AST_NODE_TYPES.TSParameterProperty &&
+                            parameterPropertyBinding(parameter)
+                                .name === name) {
+                            declarations.push(parameter);
+                        }
+                    }
+                }
+                if (classMemberName(member) === name &&
+                    member.static === isStatic) {
+                    declarations.push(member);
+                }
+            }
+            return declarations.filter((declaration) => !isSetterDeclaration(declaration));
+        };
+        /**
+         * Whether a member read resolves to a member its own class declares
+         * `: number`. Every declaration of the name has to carry the proof: an
+         * overload or a second declaration that does not is a value the read can
+         * also yield.
+         */
+        const isNumberMemberRead = (node) => {
+            if (node.computed || node.property.type !== utils_1.AST_NODE_TYPES.Identifier) {
+                return false;
+            }
+            const receiver = receiverClassContext(node.object);
+            if (!receiver) {
+                return false;
+            }
+            const declarations = classMemberDeclarations(receiver.body, node.property.name, receiver.isStatic);
+            return declarations.length > 0 && declarations.every(memberReadsNumber);
+        };
+        /**
+         * Whether a call resolves to a function the author declared `: number`
+         * returning — a free function, a method, or a function-valued class member.
+         * The callee is resolved through the scope chain, so a local that shadows a
+         * numeric helper is judged by the shadowing declaration alone; a binding
+         * reassigned to another function has to prove every write, because the
+         * declaration no longer says what the call reaches.
+         */
+        const isNumberReturningCall = (node) => {
+            const callee = unwrapWrittenKey(node.callee);
+            if (callee.type === utils_1.AST_NODE_TYPES.Identifier) {
+                const variable = ASTHelpers_1.ASTHelpers.findVariableInScope(ASTHelpers_1.ASTHelpers.getScope(context, callee), callee.name);
+                if (!variable || variable.defs.length === 0) {
+                    return false;
+                }
+                // The definition KIND decides which node carries the annotation: a
+                // function name is annotated on the function it names, while a
+                // parameter's definition node is the enclosing function — whose own
+                // return type says nothing about what the parameter holds.
+                const declaresNumeric = variable.defs.every((def) => {
+                    switch (def.type) {
+                        case utils_1.TSESLint.Scope.DefinitionType.FunctionName:
+                            return returnsNumberType(def.node);
+                        case utils_1.TSESLint.Scope.DefinitionType.Variable:
+                            // The declarator's initializer is a write, so the write pass is
+                            // what reads the annotation off the function it holds.
+                            return (def.node.type === utils_1.AST_NODE_TYPES.VariableDeclarator &&
+                                !!def.node.init);
+                        default:
+                            return false;
+                    }
+                });
+                return (declaresNumeric &&
+                    variable.references
+                        .filter((reference) => reference.isWrite())
+                        .every((reference) => !!reference.writeExpr &&
+                        returnsNumberType(unwrapWrittenKey(reference.writeExpr))));
+            }
+            if (callee.type !== utils_1.AST_NODE_TYPES.MemberExpression ||
+                callee.computed ||
+                callee.property.type !== utils_1.AST_NODE_TYPES.Identifier) {
+                return false;
+            }
+            const receiver = receiverClassContext(callee.object);
+            if (!receiver) {
+                return false;
+            }
+            const declarations = classMemberDeclarations(receiver.body, callee.property.name, receiver.isStatic);
+            return (declarations.length > 0 && declarations.every(memberCallReturnsNumber));
+        };
         /**
          * Whether the syntax alone proves the key is a number. `__proto__`,
          * `constructor` and `prototype` are never the string form of a number, so a
@@ -1027,12 +1334,15 @@ exports.enforceAssertSafeObjectKey = (0, createRule_1.createRule)({
                         isStaticallyNumeric(target.left, seen) &&
                         isStaticallyNumeric(target.right, seen));
                 case utils_1.AST_NODE_TYPES.CallExpression:
-                    return isNumericCall(target);
+                    return isNumericCall(target) || isNumberReturningCall(target);
                 case utils_1.AST_NODE_TYPES.MemberExpression:
                     // `.length` is a number on arrays, typed arrays and strings alike.
-                    return (!target.computed &&
+                    if (!target.computed &&
                         target.property.type === utils_1.AST_NODE_TYPES.Identifier &&
-                        target.property.name === 'length');
+                        target.property.name === 'length') {
+                        return true;
+                    }
+                    return isNumberMemberRead(target);
                 case utils_1.AST_NODE_TYPES.Identifier:
                     return isNumericIdentifier(target, seen);
                 default:

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

@@ -4,6 +4,7 @@ exports.enforceCentralizedMockFirestore = void 0;
 const utils_1 = require("@typescript-eslint/utils");
 const createRule_1 = require("../utils/createRule");
 const importInsertion_1 = require("../utils/importInsertion");
+const importRemoval_1 = require("../utils/importRemoval");
 /**
  * The centralized module's identity: the path segments that name it, without
  * the relative prefix a specifier needs to reach it. Keeping the identity
@@ -166,6 +167,32 @@ function retiredSpan(node) {
     }
     return undefined;
 }
+function isWithinAny(range, ranges) {
+    return ranges.some(([start, end]) => range[0] >= start && range[1] <= end);
+}
+/**
+ * The orphans the retirement carries away with it, as opposed to the ones it
+ * strands.
+ *
+ * A binding whose own declaration sits inside a retired span disappears with
+ * that span — retiring the local mock is the whole point of the fix, so the
+ * binding losing its last reference is not a defect. Every other orphan has a
+ * declaration that SURVIVES: `const myMockFirestore = jest.fn();` under
+ * `const mockFirestore = myMockFirestore;` is left bound to nothing the moment
+ * the alias goes, turning a file that lints clean into one that fails
+ * `no-unused-vars` and `noUnusedLocals` (#1900).
+ *
+ * Deleting the survivor instead is not on offer: its initializer is an
+ * arbitrary expression — `jest.fn()`, a factory call, a `require` — whose effect
+ * this fixer cannot prove absent, and dropping it would delete working code to
+ * settle a lint warning. The fix is therefore withheld and the report stands, so
+ * the local mock is still surfaced for a human to retire. An orphaned IMPORT
+ * never reaches here; the shared planner retires it in the same fix.
+ */
+const retirementCarriesOrphan = (variables, removed) => variables.every((variable) => variable.identifiers.length > 0 &&
+    variable.identifiers.every((identifier) => isWithinAny(identifier.range, removed)))
+    ? []
+    : null;
 /**
  * Collapses edits that touch, so an overlap can never rewrite a range twice.
  */
@@ -392,6 +419,18 @@ exports.enforceCentralizedMockFirestore = (0, createRule_1.createRule)({
                                     ? retirementEdit(originalText, span.start, span.end)
                                     : { start: span.start, end: span.end, text: '' });
                             }
+                            // Whatever the retired declarations were the last readers of has
+                            // to go with them, or the fix trades this report for an unused
+                            // binding the consumer's build fails on (#1900). Only the
+                            // retirements are handed over: the reference rewrites below swap
+                            // one name for another rather than deleting a declaration, and a
+                            // rewritten call to a RENAMED centralized import would otherwise
+                            // read as unbinding the very import the file is told to keep.
+                            const orphaned = (0, importRemoval_1.planOrphanedBindingRemoval)(sourceCode, removals.map(({ start, end }) => [start, end]), retirementCarriesOrphan);
+                            if (!orphaned) {
+                                return null;
+                            }
+                            const orphanRemovals = orphaned.map(([start, end]) => ({ start, end, text: '' }));
                             // Replace custom mockFirestore references with the standard one
                             const replacements = [];
                             // Add replacements for custom mockFirestore names
@@ -412,11 +451,15 @@ exports.enforceCentralizedMockFirestore = (0, createRule_1.createRule)({
                                     text: 'mockFirestore',
                                 });
                             });
-                            // A reference inside a retired declaration goes away with it, so
+                            // A reference inside a deleted range 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 &&
+                            const deletions = [...removals, ...orphanRemovals];
+                            const survivingReplacements = replacements.filter((replacement) => !deletions.some((removal) => replacement.start >= removal.start &&
                                 replacement.end <= removal.end));
-                            const edits = mergeEdits([...removals, ...survivingReplacements]);
+                            const edits = mergeEdits([
+                                ...deletions,
+                                ...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,

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

@@ -55,6 +55,30 @@ const referenceTypeNameOf = (typeName) => {
 function unwrapOptionalChain(node) {
     return node.type === utils_1.AST_NODE_TYPES.ChainExpression ? node.expression : node;
 }
+function isFunctionNode(node) {
+    return (node.type === utils_1.AST_NODE_TYPES.FunctionDeclaration ||
+        node.type === utils_1.AST_NODE_TYPES.FunctionExpression ||
+        node.type === utils_1.AST_NODE_TYPES.ArrowFunctionExpression);
+}
+/**
+ * The nearest function a node sits inside.
+ *
+ * A return statement is reached from its function through an arbitrary depth of
+ * blocks, conditionals and loops, so stepping a fixed number of parents up
+ * answers a question about indentation rather than about ownership: it finds the
+ * function only when the `return` is written directly in the body, and only for
+ * the spelling whose body is a block.
+ */
+function enclosingFunction(node) {
+    let current = node.parent;
+    while (current) {
+        if (isFunctionNode(current)) {
+            return current;
+        }
+        current = current.parent;
+    }
+    return undefined;
+}
 /**
  * The type declaration a statement makes, looking through `export`.
  *
@@ -276,6 +300,10 @@ exports.enforceFirestoreDocRefGeneric = (0, createRule_1.createRule)({
             if (nodeCache.has(node)) {
                 return nodeCache.get(node);
             }
+            // The child the walk arrived from, which is what distinguishes a function
+            // whose returned expression is under examination from one that merely
+            // contains the expression somewhere in its body.
+            let previous;
             let current = node;
             while (current) {
                 // Type assertions using 'as' keyword
@@ -295,15 +323,27 @@ exports.enforceFirestoreDocRefGeneric = (0, createRule_1.createRule)({
                     nodeCache.set(node, true);
                     return true;
                 }
-                // Return statements in functions with return type annotations
+                // Return statements in functions with return type annotations. The
+                // annotation states the schema whichever way its function is written,
+                // so a declaration, a function expression and an arrow are all read.
                 if (current.type === utils_1.AST_NODE_TYPES.ReturnStatement) {
-                    const func = current.parent?.parent;
-                    if (func?.type === utils_1.AST_NODE_TYPES.FunctionDeclaration &&
-                        func.returnType) {
+                    if (enclosingFunction(current)?.returnType) {
                         nodeCache.set(node, true);
                         return true;
                     }
                 }
+                // A concise arrow body is the returned expression itself and produces no
+                // ReturnStatement, so the branch above cannot see it. Requiring the walk
+                // to have arrived from the body keeps the annotation describing only
+                // what the function hands back: a reference built and stored inside a
+                // block body is described by nothing and still reports.
+                if (isFunctionNode(current) &&
+                    current.returnType &&
+                    current.body === previous &&
+                    current.body.type !== utils_1.AST_NODE_TYPES.BlockStatement) {
+                    nodeCache.set(node, true);
+                    return true;
+                }
                 // Assignment expressions to class properties
                 if (current.type === utils_1.AST_NODE_TYPES.AssignmentExpression) {
                     const left = current.left;
@@ -324,6 +364,7 @@ exports.enforceFirestoreDocRefGeneric = (0, createRule_1.createRule)({
                         }
                     }
                 }
+                previous = current;
                 current = current.parent;
             }
             nodeCache.set(node, false);
@@ -652,9 +693,6 @@ exports.enforceFirestoreDocRefGeneric = (0, createRule_1.createRule)({
             return false;
         }
         function findFunctionParameter(node) {
-            const isFunctionNode = (n) => n.type === utils_1.AST_NODE_TYPES.FunctionDeclaration ||
-                n.type === utils_1.AST_NODE_TYPES.FunctionExpression ||
-                n.type === utils_1.AST_NODE_TYPES.ArrowFunctionExpression;
             const findParamInFunction = (func) => {
                 const param = func.params.find((p) => p.type === utils_1.AST_NODE_TYPES.Identifier &&
                     p.name === node.name &&