@blumintinc/eslint-plugin-blumint 1.20.157 → 1.20.159

package/lib/index.js

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

package/lib/rules/enforce-f-extension-for-entry-points.js

@@ -204,7 +204,15 @@ exports.enforceFExtensionForEntryPoints = (0, createRule_1.createRule)({
         const filePath = context.filename ??
             context.getFilename();
         const fileName = path_1.default.basename(filePath);
-        const entryPoints = new Set(options.entryPoints?.length ? options.entryPoints : DEFAULT_ENTRY_POINTS);
+        // Configured names EXTEND the defaults rather than replacing them. A
+        // default only matches when it is actually imported from firebase-functions
+        // or the internal wrappers, so carrying an unused one costs nothing, while
+        // dropping one silently stops enforcing the convention for that wrapper —
+        // which is what registering a single custom trigger used to do.
+        const entryPoints = new Set([
+            ...DEFAULT_ENTRY_POINTS,
+            ...(options.entryPoints ?? []),
+        ]);
         // Only apply to files under functions/src/
         const normalizedPath = filePath.replace(/\\/g, '/');
         if (!normalizedPath.includes('/functions/src/') &&

package/lib/rules/no-excessive-parent-chain.d.ts

@@ -1,5 +1,6 @@
+import { TSESLint } from '@typescript-eslint/utils';
 type Options = [{
     max?: number;
 }];
-export declare const noExcessiveParentChain: import("@typescript-eslint/utils/dist/ts-eslint/Rule").RuleModule<"excessiveParentChain", Options, import("@typescript-eslint/utils/dist/ts-eslint/Rule").RuleListener>;
+export declare const noExcessiveParentChain: TSESLint.RuleModule<"excessiveParentChain", Options, TSESLint.RuleListener>;
 export {};

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

@@ -3,6 +3,59 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.noExcessiveParentChain = void 0;
 const utils_1 = require("@typescript-eslint/utils");
 const createRule_1 = require("../utils/createRule");
+const importRemoval_1 = require("../utils/importRemoval");
+const patternBindingRemoval_1 = require("../utils/patternBindingRemoval");
+/**
+ * How many times the cleanup below re-asks which bindings its own deletions have
+ * stranded. Each round deletes at least one declaration, so a handler would have
+ * to chain more re-destructures than this to run out — and running out declines
+ * rather than shipping half a cleanup.
+ */
+const MAX_CLEANUP_ROUNDS = 8;
+function rangesOverlap(left, right) {
+    return left[0] < right[1] && right[0] < left[1];
+}
+/**
+ * Whether an initializer is a plain read, so that deleting the declarator
+ * deletes no work the file depends on. A call, an `await` or a computed access
+ * could be doing something the surviving code still needs; a property read off
+ * an identifier is the same risk the destructuring arm already accepts, since
+ * `const { data } = event` throws on a nullish `event` exactly as `event.data`
+ * does.
+ */
+function isPureRead(node) {
+    switch (node.type) {
+        case utils_1.AST_NODE_TYPES.Identifier:
+        case utils_1.AST_NODE_TYPES.ThisExpression:
+            return true;
+        case utils_1.AST_NODE_TYPES.ChainExpression:
+        case utils_1.AST_NODE_TYPES.TSNonNullExpression:
+        case utils_1.AST_NODE_TYPES.TSAsExpression:
+            return isPureRead(node.expression);
+        case utils_1.AST_NODE_TYPES.MemberExpression:
+            return !node.computed && isPureRead(node.object);
+        default:
+            return false;
+    }
+}
+/** The declarator a binding comes from, when exactly one declares it. */
+function declaratorOf(variable) {
+    if (variable.defs.length !== 1)
+        return null;
+    const [definition] = variable.defs;
+    if (definition.type !== utils_1.TSESLint.Scope.DefinitionType.Variable)
+        return null;
+    return definition.node;
+}
+/**
+ * A parameter is part of its function's signature, so a rewrite of a read inside
+ * the body has no license to change it. Left in place rather than declined:
+ * an unused parameter is legal and is what `args: 'none'` already permits.
+ */
+function isParameterBinding(variable) {
+    return (variable.defs.length > 0 &&
+        variable.defs.every((definition) => definition.type === utils_1.TSESLint.Scope.DefinitionType.Parameter));
+}
 // Maximum number of consecutive .parent calls allowed before warning
 const DEFAULT_MAX_PARENT_CHAIN_LENGTH = 2;
 // Handler types that this rule applies to
@@ -40,6 +93,7 @@ exports.noExcessiveParentChain = (0, createRule_1.createRule)({
     defaultOptions: [{}],
     create(context) {
         const maxParentChainLength = context.options[0]?.max ?? DEFAULT_MAX_PARENT_CHAIN_LENGTH;
+        const sourceCode = context.getSourceCode();
         // Track variables that contain event data
         const eventDataVariables = new Map();
         const eventIdentifiers = new Set();
@@ -84,6 +138,189 @@ exports.noExcessiveParentChain = (0, createRule_1.createRule)({
             }
             return outermost;
         };
+        /**
+         * The binding a name denotes at the point the suggestion writes it, resolved
+         * through the scope chain rather than matched by text: a shadowing local
+         * carrying the same spelling as the event binding is a different binding, and
+         * mistaking one for the other is how a fixer came to rewrite an import the
+         * reported call never resolved to (#1903).
+         */
+        const resolveInScope = (scope, name) => {
+            for (let current = scope; current; current = current.upper) {
+                const variable = current.variables.find((candidate) => candidate.name === name);
+                if (variable)
+                    return variable;
+            }
+            return null;
+        };
+        /**
+         * The coarse second opinion the destructuring planner takes, for the bindings
+         * it does not own. Scope analysis and a plain name scan can disagree, and a
+         * removal that turns out to be wrong deletes working code. The scan is
+         * windowed to the scope that declares the binding, since an occurrence of a
+         * function-local name outside that function belongs to another binding.
+         */
+        const nameSurvivesRemoval = (variable, ranges) => {
+            const scope = variable.scope.block.range;
+            const elsewhere = [
+                [0, scope[0]],
+                [scope[1], sourceCode.text.length],
+            ];
+            return (0, importRemoval_1.nameOccursOutside)(sourceCode, variable.name, [...ranges, ...elsewhere], variable.identifiers.map((identifier) => identifier.range));
+        };
+        /**
+         * The ranges that unbind `variables` declared by a plain `const x = ...`, or
+         * `null` when any of them cannot be unbound safely.
+         *
+         * The destructuring counterpart lives in `planPatternBindingRemoval`; this
+         * arm exists because a chain roots just as often at an intermediate read
+         * (`const afterRef = change.after`) as at a destructured property.
+         */
+        const planIdentifierBindingRemoval = (variables, removed) => {
+            const byDeclaration = new Map();
+            for (const variable of variables) {
+                const declarator = declaratorOf(variable);
+                if (!declarator || declarator.id.type !== utils_1.AST_NODE_TYPES.Identifier) {
+                    return null;
+                }
+                const declaration = declarator.parent;
+                if (!declaration ||
+                    declaration.type !== utils_1.AST_NODE_TYPES.VariableDeclaration) {
+                    return null;
+                }
+                // `const` is what makes "nothing reads it" the whole story: a `let` can
+                // be assigned from anywhere its scope reaches, and an assignment is not
+                // a read.
+                if (declaration.kind !== 'const' || declaration.declare)
+                    return null;
+                // The ranges below span separators, so a comment among the declarators
+                // would be swallowed or stranded depending on where it sits.
+                if (sourceCode.getCommentsInside(declaration).length > 0)
+                    return null;
+                if (!declarator.init || !isPureRead(declarator.init))
+                    return null;
+                const group = byDeclaration.get(declaration);
+                if (group) {
+                    group.add(declarator);
+                }
+                else {
+                    byDeclaration.set(declaration, new Set([declarator]));
+                }
+            }
+            const ranges = [];
+            for (const [declaration, dropped] of byDeclaration) {
+                const siblings = declaration.declarations;
+                if (siblings.some((sibling) => !dropped.has(sibling))) {
+                    const runs = (0, importRemoval_1.removalRuns)(siblings.map((sibling) => ({
+                        range: sibling.range,
+                        removed: dropped.has(sibling),
+                    })));
+                    if (!runs)
+                        return null;
+                    ranges.push(...runs);
+                    continue;
+                }
+                if (!(0, patternBindingRemoval_1.isFreestandingStatement)(declaration))
+                    return null;
+                const range = (0, importRemoval_1.statementRemovalRange)(sourceCode, declaration);
+                if (!range)
+                    return null;
+                ranges.push(range);
+            }
+            for (const variable of variables) {
+                if (nameSurvivesRemoval(variable, [...removed, ...ranges]))
+                    return null;
+            }
+            return ranges;
+        };
+        /**
+         * The extra ranges the suggestion must delete so that replacing the chain
+         * leaves no binding bound to nothing, `[]` when the rewrite strands nothing,
+         * or `null` when something would be stranded that cannot be unbound safely.
+         *
+         * `null` withholds the whole suggestion. Rewriting anyway would trade this
+         * rule's report for a `no-unused-vars` one on a file that was clean, and
+         * since accepting the suggestion resolves the report, nothing revisits the
+         * debt (#2026).
+         *
+         * Deleting a declaration strands whatever that declaration READ, so the
+         * question is re-asked until it settles: `const { after } = change` goes
+         * first, and only then is `const { data: change } = event` unreferenced. The
+         * binding the replacement text itself names is exempt throughout — the
+         * inserted `event.params` is a reference the source does not yet contain, so
+         * scope analysis alone would read the event binding as stranded.
+         */
+        const planOrphanCleanup = (chainRange, eventVariable) => {
+            const removed = [chainRange];
+            const extra = [];
+            const handled = new Set();
+            for (let round = 0; round < MAX_CLEANUP_ROUNDS; round++) {
+                const orphans = (0, importRemoval_1.orphanedBindings)(sourceCode, removed).filter((variable) => variable !== eventVariable &&
+                    !handled.has(variable) &&
+                    !isParameterBinding(variable));
+                if (orphans.length === 0) {
+                    return extra.sort((left, right) => left[0] - right[0]);
+                }
+                const patterns = [];
+                const identifiers = [];
+                for (const variable of orphans) {
+                    handled.add(variable);
+                    const declarator = declaratorOf(variable);
+                    // An orphan bound by an import, a type alias or anything else this
+                    // rule cannot rewrite declines rather than being guessed at.
+                    if (!declarator)
+                        return null;
+                    if (declarator.id.type === utils_1.AST_NODE_TYPES.ObjectPattern) {
+                        patterns.push(variable);
+                    }
+                    else if (declarator.id.type === utils_1.AST_NODE_TYPES.Identifier) {
+                        identifiers.push(variable);
+                    }
+                    else {
+                        return null;
+                    }
+                }
+                const planned = [];
+                if (patterns.length > 0) {
+                    const plan = (0, patternBindingRemoval_1.planPatternBindingRemoval)(sourceCode, patterns, removed);
+                    if (!plan)
+                        return null;
+                    planned.push(...plan);
+                }
+                if (identifiers.length > 0) {
+                    const plan = planIdentifierBindingRemoval(identifiers, removed);
+                    if (!plan)
+                        return null;
+                    planned.push(...plan);
+                }
+                if (planned.length === 0)
+                    return null;
+                extra.push(...planned);
+                removed.push(...planned);
+            }
+            return null;
+        };
+        /**
+         * The edits of the suggestion, or `null` to withdraw it. ESLint drops a
+         * suggestion whose fix yields nothing, which is how the unsafe cases above
+         * decline.
+         */
+        const buildSuggestionFixes = (fixer, outermost, eventParamName, eventVariable) => {
+            const cleanup = planOrphanCleanup(outermost.range, eventVariable);
+            if (!cleanup)
+                return null;
+            // ESLint throws out the whole report when one fix's ranges overlap, so a
+            // cleanup that collides with the rewrite (or with itself) is withheld
+            // rather than allowed to take the pass down with it.
+            const ranges = [outermost.range, ...cleanup];
+            const collides = ranges.some((range, index) => ranges.some((other, otherIndex) => index !== otherIndex && rangesOverlap(range, other)));
+            if (collides)
+                return null;
+            return [
+                fixer.replaceText(outermost, `${eventParamName}.params`),
+                ...cleanup.map((range) => fixer.removeRange([range[0], range[1]])),
+            ];
+        };
         const hasRefProperty = (node) => {
             let current = node;
             while (current) {
@@ -282,6 +519,9 @@ exports.noExcessiveParentChain = (0, createRule_1.createRule)({
                     return;
                 }
                 const eventParamName = resolveEventParamName(rootIdentifier);
+                const eventVariable = eventParamName
+                    ? resolveInScope(context.getScope(), eventParamName)
+                    : null;
                 context.report({
                     node,
                     messageId: 'excessiveParentChain',
@@ -296,7 +536,7 @@ exports.noExcessiveParentChain = (0, createRule_1.createRule)({
                                     count: parentCount,
                                 },
                                 fix(fixer) {
-                                    return fixer.replaceText(getOutermostParentHop(node), `${eventParamName}.params`);
+                                    return buildSuggestionFixes(fixer, getOutermostParentHop(node), eventParamName, eventVariable);
                                 },
                             },
                         ]

package/lib/utils/patternBindingRemoval.d.ts

@@ -13,8 +13,15 @@
  * through `planOrphanedBindingRemoval`, which re-examines the plan for exactly
  * that.
  */
-import { TSESLint } from '@typescript-eslint/utils';
+import { TSESLint, TSESTree } from '@typescript-eslint/utils';
 import { ImportRemovalSource, TextRange } from './importRemoval';
+/**
+ * Whether the declaration is a statement in its own right, and so can be
+ * deleted whole. A `for (const { data } of events)` head reads as a declaration
+ * too, and deleting one leaves a `for` with no binding at all; an
+ * `export const` keeps its `export` keyword outside the declaration's own range.
+ */
+export declare function isFreestandingStatement(declaration: TSESTree.VariableDeclaration): boolean;
 /**
  * The ranges that unbind `variables` from the destructuring patterns declaring
  * them, or `null` when any of them cannot be unbound safely.

package/lib/utils/patternBindingRemoval.js

@@ -15,7 +15,7 @@
  * that.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.planPatternBindingRemoval = void 0;
+exports.planPatternBindingRemoval = exports.isFreestandingStatement = void 0;
 const utils_1 = require("@typescript-eslint/utils");
 const importRemoval_1 = require("./importRemoval");
 function patternBindingOf(variable) {
@@ -50,6 +50,7 @@ function isFreestandingStatement(declaration) {
         parent?.type === utils_1.AST_NODE_TYPES.SwitchCase ||
         parent?.type === utils_1.AST_NODE_TYPES.TSModuleBlock);
 }
+exports.isFreestandingStatement = isFreestandingStatement;
 /**
  * The properties of `pattern` that bind nothing but orphans, or `null` when one
  * of them cannot be dropped without changing what the declaration does.

package/package.json

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

package/release-manifest.json

@@ -1,4 +1,32 @@
 [
+  {
+    "version": "1.20.159",
+    "date": "2026-08-17T02:05:07.694Z",
+    "rules": [
+      {
+        "name": "enforce-f-extension-for-entry-points",
+        "changeType": "fix",
+        "issues": [
+          2027
+        ],
+        "summary": "extend the default entry points rather than replacing them (closes #2027)"
+      }
+    ]
+  },
+  {
+    "version": "1.20.158",
+    "date": "2026-08-16T14:52:13.506Z",
+    "rules": [
+      {
+        "name": "no-excessive-parent-chain",
+        "changeType": "fix",
+        "issues": [
+          2026
+        ],
+        "summary": "remove the binding the suggestion de-references"
+      }
+    ]
+  },
   {
     "version": "1.20.157",
     "date": "2026-08-16T06:24:21.626Z",