@blumintinc/eslint-plugin-blumint 1.21.5 → 1.21.7

package/lib/index.js

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

package/lib/rules/global-const-style.js

@@ -306,16 +306,122 @@ const isWriteTarget = (node) => {
     }
 };
 /**
- * Whether the binding is written through anywhere in the file. Answered from
- * the scope manager's reference list rather than a textual search for the
- * name, so a same-named binding in another scope (`const arr` shadowed inside a
- * callback) contributes nothing, and a same-named method on an unrelated
- * receiver (`other.push(1)`) is never even visited.
+ * The composite literal a reference is STORED INTO — the object in
+ * `{ items: ITEMS }`, the array in `[ITEMS]` — or null for every other
+ * position.
+ *
+ * Storing a reference does not copy it: the same array stays reachable through
+ * the container, so `holder.items.push(3)` writes through to the binding
+ * exactly as a direct alias does, and freezing it raises the same TS2339. A
+ * `SpreadElement` is excluded because it genuinely builds a fresh value
+ * (`const COPY = [...ITEMS]`), and a computed key is excluded because it coerces
+ * the reference to a property name rather than retaining it.
  */
-const isBindingMutated = (variable) => variable.references.some((reference) => {
-    const path = accessPathOf(reference.identifier);
-    return path !== null && (isMutatingMethodCall(path) || isWriteTarget(path));
-});
+const storageContainerOf = (node) => {
+    const parent = node.parent;
+    if (!parent) {
+        return null;
+    }
+    if (parent.type === utils_1.AST_NODE_TYPES.Property &&
+        parent.value === node &&
+        parent.parent?.type === utils_1.AST_NODE_TYPES.ObjectExpression) {
+        return parent.parent;
+    }
+    if (parent.type === utils_1.AST_NODE_TYPES.ArrayExpression &&
+        parent.elements.some((element) => element === node)) {
+        return parent;
+    }
+    return null;
+};
+/**
+ * The declarator a reference initializes IN WHOLE — `OTHER` in
+ * `const OTHER = ITEMS` — or null for every other position. Such a declaration
+ * introduces a second name for one value, so whatever is done to that name is
+ * done to this binding.
+ *
+ * Type wrappers are climbed because they annotate a value without replacing it:
+ * `const OTHER = ITEMS!` and `const OTHER = ITEMS satisfies T` denote the same
+ * array as the bare form, and each breaks the same way once it is frozen. A
+ * cast that erases the element type (`ITEMS as any`) is climbed on the same
+ * terms, which withholds the assertion from a mutation the compiler would have
+ * tolerated — staying silent is the cheap error here, emitting a fix that stops
+ * the file compiling is not.
+ *
+ * A reference STORED INTO a composite literal is followed through that
+ * container, since storing does not copy — see `storageContainerOf`. A
+ * destructuring id extracts a member rather than the whole, so it is not an
+ * alias here.
+ */
+const aliasDeclaratorOf = (identifier) => {
+    // Ascends strictly, so reaching a node with no parent terminates the walk.
+    let value = outermostValueOf(identifier);
+    for (;;) {
+        const declarator = value.parent;
+        if (declarator?.type === utils_1.AST_NODE_TYPES.VariableDeclarator &&
+            declarator.init === value &&
+            declarator.id.type === utils_1.AST_NODE_TYPES.Identifier) {
+            return declarator;
+        }
+        const container = storageContainerOf(value);
+        if (!container) {
+            return null;
+        }
+        value = outermostValueOf(container);
+    }
+};
+/**
+ * Whether the binding is written through anywhere in the file, under its own
+ * name or through an alias of it. Answered from the scope manager's reference
+ * list rather than a textual search for the name, so a same-named binding in
+ * another scope (`const arr` shadowed inside a callback) contributes nothing,
+ * and a same-named method on an unrelated receiver (`other.push(1)`) is never
+ * even visited.
+ *
+ * The walk follows aliases because a binding's own reference list is not where
+ * a mutation through one is recorded: in
+ * `const OTHER = ITEMS; OTHER.push(3);` the mutating call references `OTHER`, a
+ * separate variable this one never enrols, and reading only `ITEMS`'s
+ * references sees a plain read. Appending `as const` there emits TS2339 for an
+ * input that compiled (Issue #2324). Following is transitive — every hop names
+ * the one value — and `visited` keeps a chain that leads back on itself, which
+ * a redeclared `var` can build, from looping forever.
+ *
+ * The declaring KEYWORD is deliberately not screened. `as const` types the
+ * value `readonly`, and a binding takes its declared type from its initializer,
+ * so `let other = ITEMS; other.push(3);` is the same TS2339 as the `const`
+ * spelling; reassigning such a `let` does not recover mutability either,
+ * because the reassignment is then rejected against that same frozen type. A
+ * check keyed on `const` would leave the `let` spelling breaking builds under
+ * `--fix`.
+ */
+const isBindingMutated = (variable, declaredVariablesOf) => {
+    // Grown in place and walked by index: an alias found mid-walk is appended and
+    // reached by the same loop, so the traversal needs no recursion of its own.
+    const pending = [variable];
+    const visited = new Set(pending);
+    for (let index = 0; index < pending.length; index += 1) {
+        for (const reference of pending[index].references) {
+            const path = accessPathOf(reference.identifier);
+            if (path !== null) {
+                if (isMutatingMethodCall(path) || isWriteTarget(path)) {
+                    return true;
+                }
+                continue;
+            }
+            const declarator = aliasDeclaratorOf(reference.identifier);
+            if (!declarator) {
+                continue;
+            }
+            for (const alias of declaredVariablesOf(declarator)) {
+                if (!visited.has(alias)) {
+                    visited.add(alias);
+                    pending.push(alias);
+                }
+            }
+        }
+    }
+    return false;
+};
 /**
  * Walks the scope chain upward from `scope` (inclusive) and reports whether
  * `targetName` is bound anywhere between `scope` and `stopScope` (inclusive).
@@ -531,6 +637,14 @@ exports.default = (0, createRule_1.createRule)({
             return (target.type === utils_1.AST_NODE_TYPES.Identifier &&
                 !PRIMITIVE_VALUE_GLOBALS.has(target.name));
         };
+        /**
+         * The bindings a declaration node introduces, as the scope manager records
+         * them. The mutation walk resolves an alias declarator through this rather
+         * than looking its name up the scope chain: the scope manager already holds
+         * the exact answer, while a name lookup would have to guess which scope a
+         * `var` was hoisted into.
+         */
+        const declaredVariablesOf = (node) => context.getDeclaredVariables(node);
         const describeValueKind = (node) => {
             const target = unwrapValueWrappers(node);
             if (target.type === utils_1.AST_NODE_TYPES.ArrayExpression) {
@@ -722,7 +836,8 @@ exports.default = (0, createRule_1.createRule)({
                             const declaredVariable = context
                                 .getDeclaredVariables(declaration)
                                 .find((variable) => variable.name === name);
-                            return !declaredVariable || !isBindingMutated(declaredVariable);
+                            return (!declaredVariable ||
+                                !isBindingMutated(declaredVariable, declaredVariablesOf));
                         };
                         if (shouldHaveAsConst(init)) {
                             context.report({

package/lib/rules/no-try-catch-already-exists-in-transaction.d.ts

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

package/lib/rules/no-try-catch-already-exists-in-transaction.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.noTryCatchAlreadyExistsInTransaction = void 0;
 const utils_1 = require("@typescript-eslint/utils");
+const ASTHelpers_1 = require("../utils/ASTHelpers");
 const createRule_1 = require("../utils/createRule");
 const ALREADY_EXISTS_STRINGS = new Set(['already-exists', 'ALREADY_EXISTS']);
 const ALREADY_EXISTS_NUMBERS = new Set([6, '6']);
@@ -24,6 +25,142 @@ function isRunTransactionCall(node) {
     }
     return false;
 }
+/**
+ * The package surfaces whose `runTransaction` is the Firestore one.
+ *
+ * The bare name is not unique to Firestore: `firebase/database` exports a
+ * `runTransaction` for the Realtime Database, which re-applies its update
+ * function locally on conflict and carries no gRPC status codes, so
+ * `ALREADY_EXISTS` is not part of its error model and neither remedy this rule
+ * offers exists there — `runCreateForgivenessTransaction` is backend-Firestore
+ * only. Reporting an RTDB transaction leaves a developer with no way to comply.
+ */
+const FIRESTORE_MODULE_ROOTS = [
+    { packageSegments: ['firebase'], product: 'firestore' },
+    { packageSegments: ['firebase-admin'], product: 'firestore' },
+    { packageSegments: ['@firebase'], product: 'firestore' },
+    { packageSegments: ['@google-cloud'], product: 'firestore' },
+];
+/**
+ * Split a module source into path segments with any version suffix dropped, so
+ * a pinned specifier (`firebase@10/firestore`) reduces to the same root as the
+ * plain one. A `@` at the start of a segment marks a scope, not a version.
+ */
+function moduleSegments(source) {
+    return source.split('/').map((segment) => {
+        const versionIndex = segment.indexOf('@', 1);
+        return versionIndex === -1 ? segment : segment.slice(0, versionIndex);
+    });
+}
+/**
+ * Match the package root structurally rather than against one spelling: a deep
+ * entry point (`firebase/firestore/lite`), a build variant
+ * (`@firebase/firestore-compat`) and a pinned version all name the same
+ * product, and a trailing segment must not defeat the check.
+ */
+function isFirestoreModuleSource(source) {
+    const segments = moduleSegments(source);
+    return FIRESTORE_MODULE_ROOTS.some(({ packageSegments, product }) => {
+        if (!packageSegments.every((segment, index) => segments[index] === segment)) {
+            return false;
+        }
+        const productSegment = segments[packageSegments.length];
+        return (productSegment === product || !!productSegment?.startsWith(`${product}-`));
+    });
+}
+/**
+ * First segments that mark a path alias into the project's own tree rather than
+ * a published package. A scoped package's first segment is `@scope`, so a bare
+ * `@` can only be an alias.
+ */
+const FIRST_PARTY_SOURCE_ROOTS = new Set(['@', '~', 'src', 'app', 'lib']);
+/**
+ * Whether a specifier names a published package, which is the only thing that
+ * can REFUTE Firestore provenance.
+ *
+ * A relative or absolute path, or a path alias, resolves into first-party code
+ * this rule cannot follow, so such a source says nothing about which product
+ * the binding came from. Reading its failure to look like `firebase/firestore`
+ * as proof of a different product is what silenced the rule on every
+ * `import { db } from '../../config/firebaseAdmin'` re-export.
+ */
+function isBarePackageSource(source) {
+    if (source.startsWith('.') || source.startsWith('/') || source === '') {
+        return false;
+    }
+    return !FIRST_PARTY_SOURCE_ROOTS.has(moduleSegments(source)[0]);
+}
+/**
+ * The module `name` is imported from, or null when the file declares the name
+ * itself (a local helper, a parameter) or nothing declares it at all.
+ */
+function importedSourceOf(scope, name) {
+    const variable = ASTHelpers_1.ASTHelpers.findVariableInScope(scope, name);
+    if (!variable) {
+        return null;
+    }
+    for (const def of variable.defs) {
+        const specifier = def.node;
+        if (specifier.type !== utils_1.AST_NODE_TYPES.ImportSpecifier &&
+            specifier.type !== utils_1.AST_NODE_TYPES.ImportDefaultSpecifier &&
+            specifier.type !== utils_1.AST_NODE_TYPES.ImportNamespaceSpecifier) {
+            continue;
+        }
+        const declaration = specifier.parent;
+        if (declaration?.type !== utils_1.AST_NODE_TYPES.ImportDeclaration ||
+            typeof declaration.source.value !== 'string') {
+            continue;
+        }
+        return declaration.source.value;
+    }
+    return null;
+}
+/**
+ * The identifier whose binding carries the call's provenance: the callee for
+ * `runTransaction(...)`, and the root of the member chain for
+ * `database.runTransaction(...)`, since the receiver is what an import names
+ * and the property alone matches every `<anything>.runTransaction`.
+ */
+function provenanceIdentifier(callee) {
+    if (callee.type === utils_1.AST_NODE_TYPES.Identifier) {
+        return callee;
+    }
+    let current = callee;
+    while (current.type === utils_1.AST_NODE_TYPES.MemberExpression ||
+        current.type === utils_1.AST_NODE_TYPES.ChainExpression ||
+        current.type === utils_1.AST_NODE_TYPES.TSNonNullExpression) {
+        current =
+            current.type === utils_1.AST_NODE_TYPES.MemberExpression
+                ? current.object
+                : current.expression;
+    }
+    return current.type === utils_1.AST_NODE_TYPES.Identifier ? current : null;
+}
+/**
+ * Whether a `runTransaction` call is the Firestore one this rule speaks about.
+ *
+ * The gate speaks only when it knows: a binding that resolves to an import of a
+ * published package is judged by its module source, and anything else — a bare
+ * call, a parameter, a local helper, a member call on an unresolvable receiver,
+ * an import from the project's own tree — keeps the rule's posture of
+ * reporting, since a name with no traceable origin is far more often Firestore
+ * (`db.runTransaction(...)`) than not. Only a package specifier can refute
+ * Firestore; a first-party path merely fails to confirm it.
+ */
+function isFirestoreTransactionCall(node, context) {
+    if (!isRunTransactionCall(node)) {
+        return false;
+    }
+    const carrier = provenanceIdentifier(unwrapChainExpression(node.callee));
+    if (!carrier) {
+        return true;
+    }
+    const source = importedSourceOf(ASTHelpers_1.ASTHelpers.getScope(context, node), carrier.name);
+    if (source === null || !isBarePackageSource(source)) {
+        return true;
+    }
+    return isFirestoreModuleSource(source);
+}
 function getCallbackArgument(args) {
     for (const arg of args) {
         if (arg.type === utils_1.AST_NODE_TYPES.ArrowFunctionExpression ||
@@ -301,7 +438,7 @@ exports.noTryCatchAlreadyExistsInTransaction = (0, createRule_1.createRule)({
         }
         return {
             CallExpression(node) {
-                if (!isRunTransactionCall(node)) {
+                if (!isFirestoreTransactionCall(node, context)) {
                     return;
                 }
                 const callback = getCallbackArgument(node.arguments);
@@ -310,7 +447,7 @@ exports.noTryCatchAlreadyExistsInTransaction = (0, createRule_1.createRule)({
                 }
             },
             'CallExpression:exit'(node) {
-                if (!isRunTransactionCall(node)) {
+                if (!isFirestoreTransactionCall(node, context)) {
                     return;
                 }
                 const callback = getCallbackArgument(node.arguments);

package/lib/rules/prefer-sx-prop-over-system-props.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.preferSxPropOverSystemProps = void 0;
 const utils_1 = require("@typescript-eslint/utils");
+const ASTHelpers_1 = require("../utils/ASTHelpers");
 const createRule_1 = require("../utils/createRule");
 /**
  * Matches Prettier's own default. The autofix rewrites JSX that a formatter
@@ -111,7 +112,12 @@ const MUI_SYSTEM_PROPS = new Set([
     'textTransform',
 ]);
 /**
- * Default MUI component names to check. The user can extend this via options.
+ * The MUI components this rule covers.
+ *
+ * The list narrows what provenance has already selected: an element is
+ * inspected only when it resolves to an `@mui/*` import AND names one of these,
+ * so a name here can never be the whole reason an element is rewritten. The
+ * `components` option replaces the list.
  */
 const DEFAULT_MUI_COMPONENTS = new Set([
     'Box',
@@ -229,6 +235,78 @@ function isUpperCase(name) {
         name[0] === name[0].toUpperCase() &&
         name[0] !== name[0].toLowerCase());
 }
+/**
+ * The package namespace every MUI distribution publishes under: `@mui/material`,
+ * `@mui/joy`, `@mui/system`, `@mui/lab` and their deep entry points
+ * (`@mui/material/Box`).
+ */
+const MUI_PACKAGE_PREFIX = '@mui/';
+const isMuiSource = (source) => source.startsWith(MUI_PACKAGE_PREFIX);
+/**
+ * The import that introduces `name`, or null when the file declares it itself
+ * (a local component, a parameter) or nothing declares it at all.
+ */
+function importBindingOf(scope, name) {
+    const variable = ASTHelpers_1.ASTHelpers.findVariableInScope(scope, name);
+    if (!variable) {
+        return null;
+    }
+    for (const def of variable.defs) {
+        const specifier = def.node;
+        if (specifier.type !== utils_1.AST_NODE_TYPES.ImportSpecifier &&
+            specifier.type !== utils_1.AST_NODE_TYPES.ImportDefaultSpecifier &&
+            specifier.type !== utils_1.AST_NODE_TYPES.ImportNamespaceSpecifier) {
+            continue;
+        }
+        const declaration = specifier.parent;
+        if (declaration?.type !== utils_1.AST_NODE_TYPES.ImportDeclaration ||
+            typeof declaration.source.value !== 'string') {
+            continue;
+        }
+        return {
+            source: declaration.source.value,
+            // A default or namespace import has no exported name to read, so the
+            // local name is the only thing that names the component.
+            exportedName: specifier.type === utils_1.AST_NODE_TYPES.ImportSpecifier
+                ? specifier.imported.name
+                : name,
+        };
+    }
+    return null;
+}
+/**
+ * The MUI export a JSX element names, or null when the element does not come
+ * from MUI.
+ *
+ * Provenance, not spelling, is what makes an element MUI: `Box`, `Button`,
+ * `Card` and `Avatar` are ordinary words that design systems, third-party
+ * packages and first-party wrappers use too, and this rule ships a fixer that
+ * moves props into an `sx` slot a non-MUI component has no reading for. On a
+ * wrapper forwarding `width`/`height` to an `<img>`, that rewrite type-checks,
+ * lints clean and silently drops the attributes.
+ *
+ * `<Ns.Box>` resolves through `Ns`, the namespace: the object carries the
+ * provenance, so reading the property alone matches every `<Anything.Box>`.
+ */
+function muiExportOf(node, scope) {
+    const { name } = node;
+    if (name.type === utils_1.AST_NODE_TYPES.JSXIdentifier) {
+        const binding = importBindingOf(scope, name.name);
+        return binding && isMuiSource(binding.source) ? binding.exportedName : null;
+    }
+    if (name.type === utils_1.AST_NODE_TYPES.JSXMemberExpression) {
+        let object = name.object;
+        while (object.type === utils_1.AST_NODE_TYPES.JSXMemberExpression) {
+            object = object.object;
+        }
+        if (object.type !== utils_1.AST_NODE_TYPES.JSXIdentifier) {
+            return null;
+        }
+        const binding = importBindingOf(scope, object.name);
+        return binding && isMuiSource(binding.source) ? name.property.name : null;
+    }
+    return null;
+}
 /**
  * Convert a string value to a single-quoted JS string literal.
  * Used when building sx property values from JSX string attributes.
@@ -1023,9 +1101,14 @@ exports.preferSxPropOverSystemProps = (0, createRule_1.createRule)({
     },
     defaultOptions: [{}],
     create(context, [options]) {
-        const componentSet = options.components
+        // Naming a component here is the documented opt-in for a first-party
+        // wrapper that forwards its props to MUI. Such a wrapper is defined by
+        // living outside `@mui/*`, so the names the user lists are honored whatever
+        // introduced them.
+        const explicitComponents = options.components
             ? new Set(options.components)
-            : DEFAULT_MUI_COMPONENTS;
+            : null;
+        const componentSet = explicitComponents ?? DEFAULT_MUI_COMPONENTS;
         const extraAllowed = options.allowedProps
             ? new Set(options.allowedProps)
             : new Set();
@@ -1052,14 +1135,31 @@ exports.preferSxPropOverSystemProps = (0, createRule_1.createRule)({
             }
             return MUI_SYSTEM_PROPS.has(name) && !isAllowedProp(name);
         }
+        /**
+         * The MUI component this element is, or null when the rule leaves it alone.
+         * An element qualifies on two counts: it resolves to a component MUI
+         * exports, and that component is one the rule covers.
+         */
+        function targetedComponentOf(node) {
+            const writtenName = getComponentName(node);
+            if (!writtenName || !isUpperCase(writtenName)) {
+                return null;
+            }
+            if (explicitComponents?.has(writtenName)) {
+                return writtenName;
+            }
+            const muiExport = muiExportOf(node, ASTHelpers_1.ASTHelpers.getScope(context, node));
+            if (muiExport === null || !componentSet.has(muiExport)) {
+                return null;
+            }
+            // The export name, not the local one: an aliased `Box as MuiBox` is still
+            // MUI's `Box` for the covered-component and owned-prop lookups.
+            return muiExport;
+        }
         return {
             JSXOpeningElement(node) {
-                const componentName = getComponentName(node);
-                if (!componentName)
-                    return;
-                if (!isUpperCase(componentName))
-                    return;
-                if (!componentSet.has(componentName))
+                const componentName = targetedComponentOf(node);
+                if (componentName === null)
                     return;
                 const systemPropAttrs = [];
                 let sxAttr = null;

package/package.json

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

package/release-manifest.json

@@ -1,4 +1,56 @@
 [
+  {
+    "version": "1.21.7",
+    "date": "2026-09-04T21:52:00.765Z",
+    "rules": [
+      {
+        "name": "global-const-style",
+        "changeType": "fix",
+        "issues": [
+          2327
+        ],
+        "summary": "follow the binding into a container (closes #2327)"
+      },
+      {
+        "name": "no-try-catch-already-exists-in-transaction",
+        "changeType": "fix",
+        "issues": [
+          2326
+        ],
+        "summary": "report on first-party imports (closes #2326)"
+      }
+    ]
+  },
+  {
+    "version": "1.21.6",
+    "date": "2026-09-04T20:52:21.747Z",
+    "rules": [
+      {
+        "name": "global-const-style",
+        "changeType": "fix",
+        "issues": [
+          2324
+        ],
+        "summary": "follow alias chains when detecting mutation (closes #2324)"
+      },
+      {
+        "name": "no-try-catch-already-exists-in-transaction",
+        "changeType": "fix",
+        "issues": [
+          2325
+        ],
+        "summary": "gate on Firestore provenance (closes #2325)"
+      },
+      {
+        "name": "prefer-sx-prop-over-system-props",
+        "changeType": "fix",
+        "issues": [
+          2323
+        ],
+        "summary": "gate the rewrite on MUI provenance (closes #2323)"
+      }
+    ]
+  },
   {
     "version": "1.21.5",
     "date": "2026-09-04T15:01:41.191Z",