@blumintinc/eslint-plugin-blumint 1.18.3 → 1.18.5

package/lib/index.js

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

package/lib/rules/enforce-props-argument-name.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.enforcePropsArgumentName = void 0;
 const utils_1 = require("@typescript-eslint/utils");
 const createRule_1 = require("../utils/createRule");
+const ASTHelpers_1 = require("../utils/ASTHelpers");
 exports.enforcePropsArgumentName = (0, createRule_1.createRule)({
     name: 'enforce-props-argument-name',
     meta: {
@@ -195,15 +196,89 @@ exports.enforcePropsArgumentName = (0, createRule_1.createRule)({
                 }
             });
         }
+        // Determine whether renaming a constructor parameter property is unsafe to
+        // autofix. A parameter property (`private readonly foo: T`) creates BOTH a
+        // constructor-local binding and a `this.foo` class field, so a
+        // declaration-only rename would leave dangling references: plain `foo`
+        // usages inside the constructor (e.g. `super(foo)`) and `this.foo` accesses
+        // anywhere in the class. Mirrors #1123 — when a rename cannot be applied
+        // everywhere syntactically, emit no fix rather than corrupt the code.
+        function parameterPropertyRenameIsUnsafe(classNode, name, declarationId) {
+            let unsafe = false;
+            const visit = (node) => {
+                if (unsafe) {
+                    return;
+                }
+                if (node.type === utils_1.AST_NODE_TYPES.MemberExpression &&
+                    node.object.type === utils_1.AST_NODE_TYPES.ThisExpression &&
+                    node.property.type === utils_1.AST_NODE_TYPES.Identifier &&
+                    node.property.name === name) {
+                    unsafe = true;
+                    return;
+                }
+                if (node.type === utils_1.AST_NODE_TYPES.Identifier &&
+                    node.name === name &&
+                    node !== declarationId) {
+                    unsafe = true;
+                    return;
+                }
+                for (const key of Object.keys(node)) {
+                    if (key === 'parent') {
+                        continue;
+                    }
+                    const value = node[key];
+                    if (Array.isArray(value)) {
+                        for (const child of value) {
+                            if (ASTHelpers_1.ASTHelpers.isNode(child)) {
+                                visit(child);
+                            }
+                        }
+                    }
+                    else if (ASTHelpers_1.ASTHelpers.isNode(value)) {
+                        visit(value);
+                    }
+                }
+            };
+            visit(classNode);
+            return unsafe;
+        }
+        // Find the class (declaration or expression) that owns a method definition.
+        function getEnclosingClass(node) {
+            const classBody = node.parent;
+            if (classBody && classBody.type === utils_1.AST_NODE_TYPES.ClassBody) {
+                const classNode = classBody.parent;
+                if (classNode &&
+                    (classNode.type === utils_1.AST_NODE_TYPES.ClassDeclaration ||
+                        classNode.type === utils_1.AST_NODE_TYPES.ClassExpression)) {
+                    return classNode;
+                }
+            }
+            return null;
+        }
         // Check class method parameters (including constructors)
         function checkClassMethod(node) {
             const method = node.value;
             const sourceCode = context.sourceCode;
             const propsParams = getPropsParams(method.params);
+            // When the enclosing class extends a base class, a constructor parameter
+            // property (e.g. `private readonly fullProps: SubProps`) cannot be safely
+            // renamed to `props`: the base class may already declare a private `props`
+            // field/parameter-property, so the rename would create a TS2415 private-
+            // field collision, and it would also leave `super(fullProps)` / `this.
+            // fullProps` references dangling. The rule is purely syntactic and cannot
+            // inspect the base class, so it defers to TypeScript correctness here and
+            // does not report on parameter properties in subclasses (this repo prefers
+            // false negatives over false positives).
+            const enclosingClass = getEnclosingClass(node);
+            const classExtendsBase = !!enclosingClass?.superClass;
             method.params.forEach((param) => {
                 if (isDestructuredParameter(param)) {
                     return;
                 }
+                if (classExtendsBase &&
+                    param.type === utils_1.AST_NODE_TYPES.TSParameterProperty) {
+                    return;
+                }
                 const id = getIdFromParam(param);
                 if (id && id.typeAnnotation && id.typeAnnotation.typeAnnotation) {
                     const typeName = getTypeName(id.typeAnnotation.typeAnnotation);
@@ -221,6 +296,15 @@ exports.enforcePropsArgumentName = (0, createRule_1.createRule)({
                                     suggestedName,
                                 },
                                 fix: (fixer) => {
+                                    // A parameter-property rename touches both the parameter and
+                                    // the `this.<name>` field; refuse to autofix when the name is
+                                    // referenced elsewhere, since a declaration-only rename would
+                                    // leave dangling references.
+                                    if (param.type === utils_1.AST_NODE_TYPES.TSParameterProperty &&
+                                        enclosingClass &&
+                                        parameterPropertyRenameIsUnsafe(enclosingClass, id.name, id)) {
+                                        return null;
+                                    }
                                     const token = sourceCode.getFirstToken(id);
                                     if (!token)
                                         return null;

package/lib/rules/enforce-singular-type-names.js

@@ -25,6 +25,7 @@ var __importStar = (this && this.__importStar) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.enforceSingularTypeNames = void 0;
 const createRule_1 = require("../utils/createRule");
+const utils_1 = require("@typescript-eslint/utils");
 const pluralize = __importStar(require("pluralize"));
 const NON_PLURALIZABLE_SUFFIXES = [
     'Props',
@@ -33,6 +34,66 @@ const NON_PLURALIZABLE_SUFFIXES = [
     'Settings',
     'Data',
 ];
+/**
+ * Generic references whose instantiation is itself a container: `Array<T>` and
+ * `ReadonlyArray<T>`. `Readonly<T>` is handled separately — it is an identity
+ * wrapper that preserves T's shape, so we recurse into T rather than treating
+ * the reference itself as a container.
+ */
+const ARRAY_GENERIC_NAMES = new Set(['Array', 'ReadonlyArray']);
+/**
+ * Returns true when the type alias RHS resolves to a container shape — a
+ * `TSArrayType` (`Foo[]`) or `TSTupleType` (`[A, B]`) — for which a plural name
+ * is the correct, self-documenting choice. Sees through identity-ish wrappers
+ * over the same shape: the `readonly` type operator, parenthesized types, and
+ * the `Readonly<T>` utility type; `Array<T>`/`ReadonlyArray<T>` are containers
+ * outright.
+ */
+function resolvesToContainerType(node) {
+    let current = node;
+    // Fixpoint loop: peel identity wrappers until a concrete shape is reached.
+    // Wrappers are finite; the cap only guards against a pathological cycle.
+    for (let i = 0; i < 10; i++) {
+        switch (current.type) {
+            case utils_1.AST_NODE_TYPES.TSArrayType:
+            case utils_1.AST_NODE_TYPES.TSTupleType:
+                return true;
+            case utils_1.AST_NODE_TYPES.TSTypeOperator: {
+                const operator = current;
+                if (operator.operator !== 'readonly' || !operator.typeAnnotation) {
+                    return false;
+                }
+                current = operator.typeAnnotation;
+                continue;
+            }
+            case utils_1.AST_NODE_TYPES.TSTypeReference: {
+                const ref = current;
+                if (ref.typeName.type !== utils_1.AST_NODE_TYPES.Identifier)
+                    return false;
+                if (ARRAY_GENERIC_NAMES.has(ref.typeName.name))
+                    return true;
+                if (ref.typeName.name === 'Readonly' &&
+                    ref.typeParameters &&
+                    ref.typeParameters.params.length > 0) {
+                    current = ref.typeParameters.params[0];
+                    continue;
+                }
+                return false;
+            }
+            default: {
+                // Parentheses (`(Foo[])`) — the parser may emit TSParenthesizedType.
+                // Matched by string since the node type is not always in the enum.
+                if (current.type === 'TSParenthesizedType' &&
+                    'typeAnnotation' in current) {
+                    current = current.typeAnnotation;
+                    continue;
+                }
+                return false;
+            }
+        }
+    }
+    return false;
+}
 exports.enforceSingularTypeNames = (0, createRule_1.createRule)({
     create(context) {
         /**
@@ -82,9 +143,15 @@ exports.enforceSingularTypeNames = (0, createRule_1.createRule)({
             // Check type aliases
             TSTypeAliasDeclaration(node) {
                 const name = node.id.name;
-                if (isPlural(name)) {
-                    reportPluralName(node.id, name, getSingularForm(name));
-                }
+                if (!isPlural(name))
+                    return;
+                // A plural name correctly models a container type (array/tuple),
+                // including through identity-ish wrappers (Readonly<>, readonly, parens),
+                // so exempt it — matching the rule message's "leaves plural names for
+                // container types" promise.
+                if (resolvesToContainerType(node.typeAnnotation))
+                    return;
+                reportPluralName(node.id, name, getSingularForm(name));
             },
             // Check interfaces
             TSInterfaceDeclaration(node) {

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

@@ -139,6 +139,21 @@ const DEFAULT_MUI_COMPONENTS = new Set([
     'AppBar',
     'Toolbar',
 ]);
+/**
+ * Components whose public prop API defines `color` as a closed semantic enum
+ * (a palette / variant selector like `'primary' | 'secondary' | 'error' | …`),
+ * not a CSS-forwarded system style prop. On these, `color` feeds
+ * `ownerState.color`, selecting theme variants and MUI's internal
+ * `.Mui*-color*` class selectors — moving it into `sx` both drops the variant
+ * selection and produces an invalid CSS `color` value. So `color` here is a
+ * first-class component prop, never a deprecated system prop.
+ */
+const COMPONENT_COLOR_IS_SEMANTIC = new Set([
+    'Button',
+    'IconButton',
+    'Chip',
+    'Badge',
+]);
 /**
  * Props that must never be moved to `sx` because they are genuine component
  * API props, not MUI system styling shorthands. `direction` and `spacing` are
@@ -268,7 +283,13 @@ exports.preferSxPropOverSystemProps = (0, createRule_1.createRule)({
                 return true;
             return false;
         }
-        function isSystemProp(name) {
+        function isSystemProp(name, componentName) {
+            // `color` is a semantic enum prop (not a CSS system prop) on components
+            // like Button/IconButton/Chip/Badge — exempt it there so the autofix
+            // never rewrites a variant selector into an invalid CSS color.
+            if (name === 'color' && COMPONENT_COLOR_IS_SEMANTIC.has(componentName)) {
+                return false;
+            }
             return MUI_SYSTEM_PROPS.has(name) && !isAllowedProp(name);
         }
         return {
@@ -291,7 +312,7 @@ exports.preferSxPropOverSystemProps = (0, createRule_1.createRule)({
                     if (name === 'sx') {
                         sxAttr = attr;
                     }
-                    else if (isSystemProp(name)) {
+                    else if (isSystemProp(name, componentName)) {
                         systemPropAttrs.push(attr);
                     }
                 }

package/lib/rules/react-memoize-literals.js

@@ -711,6 +711,39 @@ exports.reactMemoizeLiterals = (0, createRule_1.createRule)({
             }
             return false;
         }
+        /**
+         * True when the literal is a variable initializer whose every usage resolves
+         * to a style JSX attribute value (sx/style). This extends the inline
+         * `isStyleJSXAttributeValue` exemption across a variable: extracting an
+         * `sx`/`style` object to a local for readability is common, and the library
+         * consumes it by merging/normalizing on each render, not by reference — so
+         * memoization adds no stability benefit whether the object is inline or
+         * lifted one line above the JSX.
+         *
+         * The exemption holds only if *every* reference is a style value. If any
+         * usage flows through a call, spread, or non-style prop, that consumer can
+         * observe the reference, so the literal stays reported — the
+         * variable-mediated analogue of the inline `sx={makeSx({ … })}` guard.
+         */
+        function isStyleVariableInitializer(node) {
+            const parent = node.parent;
+            if (!parent ||
+                parent.type !== utils_1.AST_NODE_TYPES.VariableDeclarator ||
+                parent.init !== node) {
+                return false;
+            }
+            const variables = ASTHelpers_1.ASTHelpers.getDeclaredVariables(context, parent);
+            if (variables.length === 0) {
+                return false;
+            }
+            const usages = variables[0].references.filter((ref) => !ref.init);
+            // No usages (dead code): can't prove the literal only feeds a style
+            // attribute, so leave it reported (mirrors isVariableAlwaysThrown).
+            if (usages.length === 0) {
+                return false;
+            }
+            return usages.every((ref) => isStyleJSXAttributeValue(ref.identifier));
+        }
         function reportLiteral(node) {
             const descriptor = getLiteralDescriptor(node);
             if (!descriptor)
@@ -731,6 +764,12 @@ exports.reactMemoizeLiterals = (0, createRule_1.createRule)({
             if (isStyleJSXAttributeValue(node)) {
                 return;
             }
+            // Same rationale, followed across a variable: a literal assigned to a
+            // local whose every usage is a style JSX attribute value gains nothing
+            // from memoization.
+            if (isStyleVariableInitializer(node)) {
+                return;
+            }
             const hookCall = findEnclosingHookCall(node);
             if (hookCall) {
                 if (hookCall.isDirectArgument ||

package/lib/rules/require-server-timestamp-for-firestore-dates.d.ts

@@ -1,3 +1,4 @@
+import { TSESLint } from '@typescript-eslint/utils';
 type Options = [
     {
         firestoreTypePaths?: string[];
@@ -5,5 +6,5 @@ type Options = [
         ignoreTestFiles?: boolean;
     }
 ];
-export declare const requireServerTimestampForFirestoreDates: import("@typescript-eslint/utils/dist/ts-eslint/Rule").RuleModule<"useServerTimestamp", Options, import("@typescript-eslint/utils/dist/ts-eslint/Rule").RuleListener>;
+export declare const requireServerTimestampForFirestoreDates: TSESLint.RuleModule<"useServerTimestamp", Options, TSESLint.RuleListener>;
 export {};

package/lib/rules/require-server-timestamp-for-firestore-dates.js

@@ -168,6 +168,101 @@ context) {
         }
     }
 }
+// Bare Firestore write methods invoked on a document reference / DocSetter,
+// e.g. `docRef.set(payload)`, `batch.update(payload)`, `collection.add(payload)`.
+const FIRESTORE_WRITE_METHOD_NAMES = new Set(['set', 'update', 'add']);
+// Standalone Firestore write functions. These are `set`-prefixed but are writes,
+// not React state setters, so they must NOT be mistaken for a render-seed sink.
+const FIRESTORE_WRITE_FN_NAMES = new Set([
+    'setDoc',
+    'updateDoc',
+    'addDoc',
+    'setDocument',
+]);
+/**
+ * Walks up from an identifier reference through the value positions of object /
+ * array literals, spreads and casts to find the CallExpression it is an
+ * argument to. Returns that call, or null if the identifier does not flow into
+ * a call argument (e.g. it is the callee, or sits in some other position).
+ */
+function findEnclosingCallArgument(idNode) {
+    let node = idNode;
+    let parent = node.parent;
+    while (parent) {
+        if (parent.type === utils_1.AST_NODE_TYPES.CallExpression) {
+            return parent.arguments.includes(node)
+                ? parent
+                : null;
+        }
+        const canAscend = (parent.type === utils_1.AST_NODE_TYPES.Property && parent.value === node) ||
+            parent.type === utils_1.AST_NODE_TYPES.ObjectExpression ||
+            parent.type === utils_1.AST_NODE_TYPES.ArrayExpression ||
+            parent.type === utils_1.AST_NODE_TYPES.SpreadElement ||
+            parent.type === utils_1.AST_NODE_TYPES.TSAsExpression ||
+            parent.type ===
+                utils_1.AST_NODE_TYPES
+                    .TSSatisfiesExpression ||
+            parent.type === utils_1.AST_NODE_TYPES.TSNonNullExpression;
+        if (!canAscend)
+            return null;
+        node = parent;
+        parent = parent.parent;
+    }
+    return null;
+}
+/**
+ * True when the call is a Firestore write: a `.set()`/`.update()`/`.add()`
+ * member call, or a standalone `setDoc`/`updateDoc`/`addDoc`/`setDocument`.
+ */
+function isFirestoreWriteCall(call) {
+    const callee = call.callee;
+    if (callee.type === utils_1.AST_NODE_TYPES.MemberExpression &&
+        !callee.computed &&
+        callee.property.type === utils_1.AST_NODE_TYPES.Identifier &&
+        FIRESTORE_WRITE_METHOD_NAMES.has(callee.property.name)) {
+        return true;
+    }
+    return (callee.type === utils_1.AST_NODE_TYPES.Identifier &&
+        FIRESTORE_WRITE_FN_NAMES.has(callee.name));
+}
+/**
+ * True when the call hands its argument to a React state sink: a `setXxx`
+ * setter (the `useState` convention) or `useState` itself. Firestore write
+ * functions are excluded even though some share the `set` prefix.
+ */
+function isStateSetterCall(call) {
+    const callee = call.callee;
+    if (callee.type !== utils_1.AST_NODE_TYPES.Identifier)
+        return false;
+    if (callee.name === 'useState')
+        return true;
+    return (/^set[A-Z]/.test(callee.name) && !FIRESTORE_WRITE_FN_NAMES.has(callee.name));
+}
+/**
+ * A local render seed is a variable that is handed to a React state setter (or
+ * useState) and never flows into a Firestore write. Such objects are annotated
+ * with a Firestore document type only so React state can be seeded with a
+ * document-shaped value; the client clock is correct for an optimistic render,
+ * and the authoritative timestamp arrives when the Firestore subscription
+ * replaces the seed. Being *typed* as a Firestore document is not evidence that
+ * the object is *written* to Firestore.
+ */
+function isLocalRenderSeedVariable(variable) {
+    let flowsToStateSetter = false;
+    let flowsToWrite = false;
+    for (const ref of variable.references) {
+        const call = findEnclosingCallArgument(ref.identifier);
+        if (!call)
+            continue;
+        if (isFirestoreWriteCall(call)) {
+            flowsToWrite = true;
+        }
+        else if (isStateSetterCall(call)) {
+            flowsToStateSetter = true;
+        }
+    }
+    return flowsToStateSetter && !flowsToWrite;
+}
 exports.requireServerTimestampForFirestoreDates = (0, createRule_1.createRule)({
     name: 'require-server-timestamp-for-firestore-dates',
     meta: {
@@ -254,6 +349,11 @@ exports.requireServerTimestampForFirestoreDates = (0, createRule_1.createRule)({
                     typeAnnotationReferencesFirestoreType(typeAnnotation, firestoreTypeNames) &&
                     node.init &&
                     node.init.type === utils_1.AST_NODE_TYPES.ObjectExpression) {
+                    // Exempt local render seeds handed to React state, never written to
+                    // Firestore — being typed as a Firestore doc is not a write.
+                    if (context.getDeclaredVariables(node).some(isLocalRenderSeedVariable)) {
+                        return;
+                    }
                     reportNewDatesInObject(node.init, context);
                 }
             },
@@ -265,6 +365,15 @@ exports.requireServerTimestampForFirestoreDates = (0, createRule_1.createRule)({
                 const typeAnnotation = node.typeAnnotation;
                 if (!typeAnnotationReferencesFirestoreType(typeAnnotation, firestoreTypeNames))
                     return;
+                // Exempt `const seed = { ... } as FirestoreType` when `seed` is a local
+                // render seed handed to React state and never written to Firestore.
+                const parent = node.parent;
+                if (parent &&
+                    parent.type === utils_1.AST_NODE_TYPES.VariableDeclarator &&
+                    parent.init === node &&
+                    context.getDeclaredVariables(parent).some(isLocalRenderSeedVariable)) {
+                    return;
+                }
                 const inner = unwrapCast(node.expression);
                 if (inner.type === utils_1.AST_NODE_TYPES.ObjectExpression) {
                     reportNewDatesInObject(inner, context);

package/package.json

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

package/release-manifest.json

@@ -1,4 +1,56 @@
 [
+  {
+    "version": "1.18.5",
+    "date": "2026-07-09T03:26:45.486Z",
+    "rules": [
+      {
+        "name": "enforce-props-argument-name",
+        "changeType": "fix",
+        "issues": [
+          1276
+        ],
+        "summary": "exempt subclass parameter properties to avoid TS2415/TS2304 (closes #1276)"
+      }
+    ]
+  },
+  {
+    "version": "1.18.4",
+    "date": "2026-07-08T07:14:09.487Z",
+    "rules": [
+      {
+        "name": "enforce-singular-type-names",
+        "changeType": "fix",
+        "issues": [
+          1275
+        ],
+        "summary": "exempt container (array/tuple) type aliases (closes #1275)"
+      },
+      {
+        "name": "prefer-sx-prop-over-system-props",
+        "changeType": "fix",
+        "issues": [
+          1273
+        ],
+        "summary": "exempt semantic `color` on Button/IconButton/Chip/Badge (closes #1273)"
+      },
+      {
+        "name": "react-memoize-literals",
+        "changeType": "fix",
+        "issues": [
+          1274
+        ],
+        "summary": "follow sx/style exemption through variable-mediated values (closes #1274)"
+      },
+      {
+        "name": "require-server-timestamp-for-firestore-dates",
+        "changeType": "fix",
+        "issues": [
+          1272
+        ],
+        "summary": "exempt local render seeds passed to React state setters (closes #1272)"
+      }
+    ]
+  },
   {
     "version": "1.18.3",
     "date": "2026-07-06T05:16:06.067Z",