@blumintinc/eslint-plugin-blumint 1.19.21 → 1.19.23

package/lib/index.js

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

package/lib/rules/memo-compare-deeply-complex-props.js

@@ -394,6 +394,135 @@ function isReactRenderType(type) {
     }
     return false;
 }
+/**
+ * Root DOM interfaces that a concrete element type extends. Any interface whose
+ * heritage chain reaches one of these represents a live DOM node.  DOM nodes are
+ * stable references (never recreated literals), so deep-comparing them yields no
+ * benefit — and worse, walking their circular `__reactFiber$*` / `__reactProps$*`
+ * back-references risks a stack overflow.  They are excluded from the complex-prop
+ * check for the same reason `ReactElement` is.
+ */
+const DOM_ELEMENT_BASE_NAMES = new Set([
+    'HTMLElement',
+    'SVGElement',
+    'Element',
+    'Node',
+    'EventTarget',
+]);
+/**
+ * Returns true when `sym` is declared inside a DOM lib `.d.ts` file (e.g.
+ * `lib.dom.d.ts`).  Gating on this origin ensures a user-defined type that
+ * happens to be named `Element` / `Node` is still treated as a genuine data
+ * prop rather than silently carved out.  Mirrors
+ * `isSymbolFromReactDeclarationFile`, but keys on the DOM lib filename.
+ */
+function isSymbolFromDomDeclarationFile(sym) {
+    const declarations = sym.declarations;
+    if (!declarations || declarations.length === 0)
+        return false;
+    return declarations.some((decl) => {
+        const fileName = decl.getSourceFile?.()?.fileName ?? '';
+        return fileName.endsWith('.d.ts') && /lib\.dom/i.test(fileName);
+    });
+}
+/**
+ * Walks a type's base-class/heritage chain (via `getBaseTypes`) looking for a
+ * root DOM interface name. Handles concrete subclasses like `HTMLDivElement` or
+ * `HTMLButtonElement`, whose own name is not a root but whose ancestry reaches
+ * `HTMLElement` → `Element` → `Node` → `EventTarget`.
+ */
+function domHeritageIncludesElementBase(type, checker, visited) {
+    if (visited.has(type))
+        return false;
+    visited.add(type);
+    const sym = type.symbol;
+    if (sym && DOM_ELEMENT_BASE_NAMES.has(sym.escapedName)) {
+        return true;
+    }
+    if (typeof type.isClassOrInterface === 'function' &&
+        type.isClassOrInterface()) {
+        let baseTypes = [];
+        try {
+            baseTypes = checker.getBaseTypes(type);
+        }
+        catch {
+            baseTypes = [];
+        }
+        return baseTypes.some((base) => domHeritageIncludesElementBase(base, checker, visited));
+    }
+    return false;
+}
+/**
+ * Returns true when `type` resolves to a DOM element type that must be excluded
+ * from the complex-prop check. Requires BOTH that the type originates from a DOM
+ * lib `.d.ts` file AND that its heritage chain reaches a root DOM interface, so
+ * only real DOM nodes — not identically named user types — are carved out.
+ *
+ * For union types (e.g. the ubiquitous `HTMLElement | null` MUI anchor prop) the
+ * whole union counts as a DOM element only when every non-nullish member is one,
+ * so a mixed union like `HTMLElement | { theme: string }` still surfaces its
+ * genuine object member as complex.
+ */
+function isDomElementType(ts, type, checker, visited) {
+    if (visited.has(type))
+        return false;
+    visited.add(type);
+    const flags = type.flags ?? 0;
+    if ((flags & ts.TypeFlags.Union) !== 0) {
+        const nonNullishMembers = type.types.filter((member) => (member.flags &
+            (ts.TypeFlags.Null | ts.TypeFlags.Undefined | ts.TypeFlags.Void)) ===
+            0);
+        return (nonNullishMembers.length > 0 &&
+            nonNullishMembers.every((member) => isDomElementType(ts, member, checker, visited)));
+    }
+    const sym = type.symbol;
+    if (!sym)
+        return false;
+    if (!isSymbolFromDomDeclarationFile(sym))
+        return false;
+    return domHeritageIncludesElementBase(type, checker, new Set());
+}
+/**
+ * Root DOM interface names that have no shared `*Element` suffix and so must be
+ * matched exactly (unlike `HTMLDivElement`, which is caught by the family
+ * pattern below).
+ */
+const DOM_ELEMENT_TYPE_NAME_EXACT = new Set([
+    'Element',
+    'Node',
+    'EventTarget',
+    'HTMLElement',
+    'SVGElement',
+    'MathMLElement',
+]);
+/**
+ * Matches concrete DOM element interface names (`HTMLDivElement`,
+ * `HTMLButtonElement`, `SVGRectElement`, `MathMLMathElement`, …) as a family so
+ * subclasses are covered without enumerating every tag. Used only on the
+ * annotation fallback path, where the type resolves to `any` (DOM lib absent
+ * from the tsconfig `lib`) and no heritage chain is available to walk.
+ */
+const DOM_ELEMENT_SUBCLASS_PATTERN = /^(?:HTML|SVG|MathML)[A-Za-z0-9]*Element$/;
+function isDomElementTypeName(name) {
+    return (DOM_ELEMENT_TYPE_NAME_EXACT.has(name) ||
+        DOM_ELEMENT_SUBCLASS_PATTERN.test(name));
+}
+/**
+ * Origin gate for the annotation fallback path. A symbol declared in a DOM lib
+ * `.d.ts`, or with no declarations at all (the DOM lib is absent so the global
+ * resolved to `any`), is treated as DOM-sourced. A user-defined type declared in
+ * project source is not — so a coincidentally named `Element`/`Node` still
+ * flags.
+ */
+function isDomSourcedSymbol(sym) {
+    const declarations = sym.declarations;
+    if (!declarations || declarations.length === 0)
+        return true;
+    return declarations.some((decl) => {
+        const fileName = decl.getSourceFile?.()?.fileName ?? '';
+        return fileName.endsWith('.d.ts') && /lib\.dom/i.test(fileName);
+    });
+}
 function isComplexType(ts, type, checker) {
     return isComplexTypeInternal(ts, type, checker, new Set());
 }
@@ -408,6 +537,13 @@ function isComplexTypeInternal(ts, type, checker, visited) {
     if (isReactRenderType(type)) {
         return false;
     }
+    // Exclude DOM element types (e.g. the MUI `anchorEl: HTMLElement | null`)
+    // for the same reason ReactElement is excluded: DOM nodes are stable
+    // references and deep-comparing them walks React's circular fiber
+    // back-references, risking a stack overflow.
+    if (isDomElementType(ts, type, checker, new Set())) {
+        return false;
+    }
     const flags = type.flags ?? 0;
     if (isUnionType(ts, flags)) {
         return checkUnionType(ts, type, checker, visited);
@@ -545,6 +681,60 @@ function isAnnotationReactRenderType(annotationType, checker, ts) {
         return false;
     }
 }
+/**
+ * Annotation-path DOM carve-out, parallel to `isAnnotationReactRenderType`.
+ *
+ * When the DOM lib is absent from the tsconfig `lib`, a prop typed as
+ * `HTMLElement` / `HTMLDivElement` / `Element` / `Node` resolves to `any`, so
+ * the structural `isDomElementType` check cannot see it. The annotation node,
+ * however, still carries the written name via the resolved type's alias/own
+ * symbol. Match that name against the DOM element family (gated on DOM origin so
+ * a user-defined lookalike still flags). Union annotations (e.g. the ubiquitous
+ * `HTMLElement | null` MUI anchor prop) qualify only when every non-nullish
+ * member is a DOM element type.
+ */
+function isAnnotationDomElementType(annotationType, checker, ts) {
+    try {
+        const tsModule = ts;
+        if (tsModule.isUnionTypeNode?.(annotationType)) {
+            const nonNullishMembers = annotationType.types.filter((member) => {
+                if (member.kind === tsModule.SyntaxKind.NullKeyword ||
+                    member.kind === tsModule.SyntaxKind.UndefinedKeyword ||
+                    member.kind === tsModule.SyntaxKind.VoidKeyword) {
+                    return false;
+                }
+                if (tsModule.isLiteralTypeNode?.(member)) {
+                    const lit = member.literal;
+                    if (lit.kind === tsModule.SyntaxKind.NullKeyword ||
+                        lit.kind === tsModule.SyntaxKind.UndefinedKeyword) {
+                        return false;
+                    }
+                }
+                return true;
+            });
+            return (nonNullishMembers.length > 0 &&
+                nonNullishMembers.every((member) => isAnnotationDomElementType(member, checker, ts)));
+        }
+        const resolvedType = checker.getTypeFromTypeNode?.(annotationType);
+        if (!resolvedType)
+            return false;
+        // Prefer the structural heritage check when the DOM lib IS loaded.
+        if (isDomElementType(ts, resolvedType, checker, new Set())) {
+            return true;
+        }
+        // Fallback for the `any` case: the resolved type surfaces the written name
+        // via its alias (e.g. `HTMLElement`) or own symbol.
+        const sym = resolvedType
+            .aliasSymbol ?? resolvedType.symbol;
+        if (!sym)
+            return false;
+        const name = sym.escapedName;
+        return isDomElementTypeName(name) && isDomSourcedSymbol(sym);
+    }
+    catch {
+        return false;
+    }
+}
 function shouldTreatAnyAsComplex(prop, propType, ts, treatAnyAsComplex, parentTypeFlags, checker) {
     if (!(propType.flags & ts.TypeFlags.Any))
         return false;
@@ -560,6 +750,15 @@ function shouldTreatAnyAsComplex(prop, propType, ts, treatAnyAsComplex, parentTy
         isAnnotationReactRenderType(annotationType, checker, ts)) {
         return false;
     }
+    // Likewise, when the annotation resolves to a DOM element type (e.g. the MUI
+    // `anchorEl: HTMLElement | null`), the prop is a stable DOM-node reference.
+    // Deep-comparing it walks React's circular fiber back-references and yields
+    // no benefit — exclude it the same way React render types are excluded.
+    if (annotationType &&
+        checker &&
+        isAnnotationDomElementType(annotationType, checker, ts)) {
+        return false;
+    }
     return ((annotationType && annotationType.kind !== ts.SyntaxKind.AnyKeyword) ||
         (!annotationType && Boolean(parentTypeFlags & ts.TypeFlags.Object)));
 }

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

@@ -86,6 +86,21 @@ const ITERATION_METHODS = new Set([
     'flatMap',
     'sort',
 ]);
+/**
+ * Comparison operators whose result is a boolean primitive. A value produced by
+ * one of these can never carry a referential identity, so a call whose result
+ * feeds such a comparison never lets its argument's identity escape.
+ */
+const COMPARISON_OPERATORS = new Set([
+    '===',
+    '!==',
+    '==',
+    '!=',
+    '<',
+    '>',
+    '<=',
+    '>=',
+]);
 const MEMOIZATION_DEPS_TODO_PLACEHOLDER = '__TODO_MEMOIZATION_DEPENDENCIES__';
 const TODO_DEPS_COMMENT = `/* ${MEMOIZATION_DEPS_TODO_PLACEHOLDER} */`;
 const PARENTHESIZED_EXPRESSION_TYPE = utils_1.AST_NODE_TYPES.ParenthesizedExpression ??
@@ -847,6 +862,108 @@ exports.reactMemoizeLiterals = (0, createRule_1.createRule)({
             }
             return usages.every((ref) => isStyleJSXAttributeValue(ref.identifier));
         }
+        /**
+         * True when `expr` — a plain function call's result, or a reference to the
+         * variable holding that result — is consumed only for its primitive value,
+         * never by reference.
+         *
+         * Referential stability of a call's ARGUMENT matters only if the call's
+         * RESULT reaches a memoization boundary (a hook dependency, a memoized
+         * child's prop, an effect capture) where identities are reference-compared.
+         * A result that lands in a boolean-test position — a ternary/if/while/for
+         * test, a `!`, a comparison, or a logical chain that itself ends in such a
+         * position — is coerced to (or already is) a primitive, so the argument's
+         * identity provably never crosses such a boundary regardless of what the
+         * callee returns. Reasoning from how the CALLER consumes the result (not the
+         * callee's body) keeps the analysis purely syntactic and type-free.
+         *
+         * The whitelist is deliberately tight: any position not proven primitive
+         * (JSX attribute value, hook dependency element, argument to another call,
+         * spread, return, object/array member) yields false, so the exemption never
+         * silences a literal whose identity could still escape.
+         */
+        function isPrimitivelyConsumed(expr) {
+            const parent = expr.parent;
+            if (!parent) {
+                return false;
+            }
+            // TS-assertion/parenthesized wrappers are transparent to consumption:
+            // analyze how the wrapped value is ultimately used.
+            if (isExpressionWrapper(parent)) {
+                const wrapper = parent;
+                return wrapper.expression === expr && isPrimitivelyConsumed(parent);
+            }
+            switch (parent.type) {
+                case utils_1.AST_NODE_TYPES.ConditionalExpression:
+                    return parent.test === expr;
+                case utils_1.AST_NODE_TYPES.IfStatement:
+                case utils_1.AST_NODE_TYPES.WhileStatement:
+                case utils_1.AST_NODE_TYPES.DoWhileStatement:
+                case utils_1.AST_NODE_TYPES.ForStatement:
+                    return parent.test === expr;
+                case utils_1.AST_NODE_TYPES.UnaryExpression:
+                    return parent.operator === '!';
+                case utils_1.AST_NODE_TYPES.BinaryExpression:
+                    return COMPARISON_OPERATORS.has(parent.operator);
+                case utils_1.AST_NODE_TYPES.LogicalExpression:
+                    // A logical operand inherits the consumption of the whole expression:
+                    // safe only if that ultimately lands in a primitive position too.
+                    return isPrimitivelyConsumed(parent);
+                case utils_1.AST_NODE_TYPES.VariableDeclarator: {
+                    if (parent.init !== expr ||
+                        parent.id.type !== utils_1.AST_NODE_TYPES.Identifier) {
+                        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 result stays primitive, so
+                    // keep the literal reported (mirrors isStyleVariableInitializer).
+                    if (usages.length === 0) {
+                        return false;
+                    }
+                    return usages.every((ref) => isPrimitivelyConsumed(ref.identifier));
+                }
+                default:
+                    return false;
+            }
+        }
+        /**
+         * True when the literal is a direct argument of a plain function call whose
+         * result is only ever consumed primitively (see isPrimitivelyConsumed). In
+         * that case the literal's identity provably never reaches a memoization
+         * boundary — it is neither a JSX prop, nor a hook dependency, nor captured
+         * by an effect — so re-creating it each render costs nothing and memoizing
+         * it buys nothing. The callee must be a plain Identifier: member calls
+         * (`obj.method({...})`) are excluded because the receiver could retain the
+         * reference, and this keeps the guard to plain, non-hook synchronous calls.
+         */
+        function isPrimitiveConsumedCallArgument(node) {
+            // Walk up through transparent wrappers to the position the literal
+            // effectively occupies as a call argument.
+            let effective = node;
+            let parent = effective.parent;
+            while (parent &&
+                isExpressionWrapper(parent) &&
+                parent
+                    .expression === effective) {
+                effective = parent;
+                parent = effective.parent;
+            }
+            if (!parent || parent.type !== utils_1.AST_NODE_TYPES.CallExpression) {
+                return false;
+            }
+            const isDirectArgument = parent.arguments.some((arg) => arg === effective);
+            if (!isDirectArgument) {
+                return false;
+            }
+            if (parent.callee.type !== utils_1.AST_NODE_TYPES.Identifier) {
+                return false;
+            }
+            return isPrimitivelyConsumed(parent);
+        }
         function reportLiteral(node) {
             const descriptor = getLiteralDescriptor(node);
             if (!descriptor)
@@ -937,6 +1054,14 @@ exports.reactMemoizeLiterals = (0, createRule_1.createRule)({
                 });
                 return;
             }
+            // A literal passed only as an argument to a plain synchronous call whose
+            // result is consumed primitively never carries its identity to a
+            // memoization boundary, so memoizing it is pointless (issue #1329). Placed
+            // last so hook-argument and hook-return handling run first and are
+            // unaffected.
+            if (isPrimitiveConsumedCallArgument(node)) {
+                return;
+            }
             const contextLabel = formatContextLabel(owner);
             // Only emit auto-fix suggestions for simple variable initializers; other
             // contexts (returns, JSX props, nested expressions) risk unsafe rewrites.

package/package.json

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

package/release-manifest.json

@@ -1,4 +1,32 @@
 [
+  {
+    "version": "1.19.23",
+    "date": "2026-07-22T15:32:41.825Z",
+    "rules": [
+      {
+        "name": "react-memoize-literals",
+        "changeType": "fix",
+        "issues": [
+          1329
+        ],
+        "summary": "exempt literal args to primitively-consumed plain calls (closes #1329)"
+      }
+    ]
+  },
+  {
+    "version": "1.19.22",
+    "date": "2026-07-22T09:39:07.911Z",
+    "rules": [
+      {
+        "name": "memo-compare-deeply-complex-props",
+        "changeType": "fix",
+        "issues": [
+          1327
+        ],
+        "summary": "exempt DOM-node props (HTMLElement | null) from complex-prop check (closes #1327)"
+      }
+    ]
+  },
   {
     "version": "1.19.21",
     "date": "2026-07-21T21:24:23.464Z",