@blumintinc/eslint-plugin-blumint 1.17.0 → 1.17.2

package/lib/index.js

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

package/lib/rules/no-explicit-return-type.js

@@ -241,6 +241,41 @@ function isTypeGuardFunction(node) {
     }
     return false;
 }
+// The names below are the built-in TypeScript read-only wrapper types. When a
+// function is annotated with one of these, the annotation is NOT redundant:
+// TypeScript always infers the mutable concrete type (e.g. Set<T> not
+// ReadonlySet<T>), so stripping the annotation silently changes the public
+// return type and lets callers mutate internal state that the author intended
+// to protect.
+const READONLY_TYPE_NAMES = new Set([
+    'ReadonlySet',
+    'ReadonlyMap',
+    'ReadonlyArray',
+    'Readonly',
+]);
+/**
+ * Returns true when `returnType` is a read-only widening annotation — i.e.
+ * one that TypeScript would NOT infer on its own and whose removal therefore
+ * changes the public API. Two forms are covered:
+ *
+ *   TSTypeReference  — ReadonlySet<T>, ReadonlyMap<K,V>, ReadonlyArray<T>,
+ *                      Readonly<T>
+ *   TSTypeOperator   — `readonly T[]` and `readonly [a, b]` tuples
+ */
+function isReadonlyWideningReturnType(returnType) {
+    const typeAnnotation = returnType.typeAnnotation;
+    if (typeAnnotation.type === utils_1.AST_NODE_TYPES.TSTypeReference) {
+        const typeName = typeAnnotation.typeName;
+        return (typeName.type === utils_1.AST_NODE_TYPES.Identifier &&
+            READONLY_TYPE_NAMES.has(typeName.name));
+    }
+    // `readonly T[]` and `readonly [a, b]` are represented as TSTypeOperator
+    // nodes with operator === 'readonly'.
+    if (typeAnnotation.type === utils_1.AST_NODE_TYPES.TSTypeOperator) {
+        return typeAnnotation.operator === 'readonly';
+    }
+    return false;
+}
 exports.noExplicitReturnType = (0, createRule_1.createRule)({
     name: 'no-explicit-return-type',
     meta: {
@@ -297,6 +332,7 @@ exports.noExplicitReturnType = (0, createRule_1.createRule)({
                 if (!returnType)
                     return;
                 if (isTypeGuardFunction(node) ||
+                    isReadonlyWideningReturnType(returnType) ||
                     (mergedOptions.allowRecursiveFunctions && isRecursiveFunction(node))) {
                     return;
                 }
@@ -320,6 +356,7 @@ exports.noExplicitReturnType = (0, createRule_1.createRule)({
                     return;
                 }
                 if (isTypeGuardFunction(node) ||
+                    isReadonlyWideningReturnType(returnType) ||
                     (mergedOptions.allowRecursiveFunctions && isRecursiveFunction(node))) {
                     return;
                 }
@@ -334,7 +371,8 @@ exports.noExplicitReturnType = (0, createRule_1.createRule)({
                 const returnType = node.returnType;
                 if (!returnType)
                     return;
-                if (isTypeGuardFunction(node)) {
+                if (isTypeGuardFunction(node) ||
+                    isReadonlyWideningReturnType(returnType)) {
                     return;
                 }
                 context.report({
@@ -366,6 +404,7 @@ exports.noExplicitReturnType = (0, createRule_1.createRule)({
                 if (!returnType)
                     return;
                 if (isTypeGuardFunction(node.value) ||
+                    isReadonlyWideningReturnType(returnType) ||
                     (mergedOptions.allowAbstractMethodSignatures &&
                         isInterfaceOrAbstractMethodSignature(node))) {
                     return;

package/lib/rules/no-hungarian.js

@@ -10,7 +10,12 @@ const COMMON_TYPES = [
     'Boolean',
     'Array',
     'Object',
-    'Function',
+    // 'Function' is intentionally excluded. Unlike an incidental, rot-prone data
+    // type (String/Number/...), a value named *Function is intrinsically and
+    // permanently callable, so the marker can never become misleading. Fn/Func/
+    // Function are function-ROLE designators (like callback/handler/predicate),
+    // not Hungarian type tags — compareFn/mapFn are the ECMAScript/MDN-canonical
+    // parameter names. See the ABBREVIATION_MARKERS note and issue #1255.
     // 'Date', too many false positives
     'RegExp',
     'Promise',
@@ -20,16 +25,11 @@ const COMMON_TYPES = [
 // Abbreviation type markers (e.g. str, arr, obj). No English word is spelled this
 // way, so their presence as a segment — even in the middle of a name — is
 // unambiguously a type tag (strName, USER_STR_NAME, ConfigArrSettings).
-const ABBREVIATION_MARKERS = [
-    'str',
-    'num',
-    'int',
-    'bool',
-    'arr',
-    'obj',
-    'fn',
-    'func',
-];
+// `fn`/`func` are deliberately excluded: they abbreviate a value's callable ROLE
+// (like callback/handler/predicate), which is intrinsic and never rots, so
+// checkFn/compareFn/mapFn/renderFunc are legitimate role names, not Hungarian
+// type tags (#1255).
+const ABBREVIATION_MARKERS = ['str', 'num', 'int', 'bool', 'arr', 'obj'];
 // Combined type markers (former Hungarian prefixes and type suffixes)
 const TYPE_MARKERS = [
     ...ABBREVIATION_MARKERS,
@@ -53,7 +53,7 @@ const SINGLE_LETTER_PREFIXES = new Set(['b', 'i']);
 // allowed compound noun PhoneNumber. Abbreviation markers (str/arr/obj/...) are
 // deliberately excluded: no English word is spelled that way, so their presence
 // as a segment is unambiguously a type tag even inside a type name.
-const FULL_TYPE_WORDS = new Set([...COMMON_TYPES, 'Func'].map((word) => word.toLowerCase()));
+const FULL_TYPE_WORDS = new Set(COMMON_TYPES.map((word) => word.toLowerCase()));
 // Allowed descriptive suffixes that should not be flagged as Hungarian notation
 const ALLOWED_SUFFIXES = [
     'Formatted',
@@ -218,7 +218,7 @@ function splitCamelSegments(name) {
 // A TYPE name (alias/interface/class) is exempt from a full-type-word marker when
 // that marker is one clean PascalCase segment among OTHER descriptive segments —
 // i.e. the word denotes a type concept/relation, not a redundant type tag.
-// Examples: StringToNumber, CapitalizedString, PromiseOrValue, FuncKeys.
+// Examples: StringToNumber, CapitalizedString, PromiseOrValue.
 // Abbreviation markers (str/arr/obj/...) never qualify, so genuine Hungarian type
 // names like UserStrName / ConfigArrSettings / UserObjData still fire.
 function isSemanticTypeConcept(typeName) {
@@ -353,36 +353,28 @@ exports.noHungarian = (0, createRule_1.createRule)({
                     return true;
                 }
                 // Abbreviation markers (str, num, int, bool, arr, obj, fn, func) are
-                // short enough that the raw-character boundary heuristic below can fire
-                // on them as substrings inside real English words (e.g. "int" inside
-                // "Mint", "str" inside "stream"). For these markers, require an exact
-                // match against a full camelCase token so that "Mint" → ["Mint"] never
-                // matches "int", while genuine Hungarian like intValue → ["int","Value"]
-                // still does.
+                // short enough that a raw-character boundary check can fire on them as
+                // substrings inside real English words (e.g. "int" inside "Mint", "str"
+                // inside "stream"). Require an exact match against a full camelCase
+                // token so that "Mint" → ["Mint"] never matches "int", while genuine
+                // Hungarian like intValue → ["int","Value"] still does.
                 if (ABBREVIATION_MARKER_SET.has(normalizedMarker)) {
                     const segments = splitCamelSegments(variableName);
                     return segments.some((s) => s.toLowerCase() === normalizedMarker);
                 }
-                // Check for word boundaries to avoid matching substrings
-                // For example, avoid matching "int" in "points" or "str" in "stream"
-                const markerIndex = normalizedVarName.indexOf(normalizedMarker);
-                if (markerIndex === -1) {
-                    return false;
-                }
-                const preMarkerPrefix = markerIndex > 0 ? variableName[markerIndex - 1] : '';
-                const suffix = variableName[markerIndex + normalizedMarker.length] ?? '';
-                // Ensure we have proper word boundaries
-                // A word boundary is defined by:
-                // 1. Start of string OR underscore OR capital letter before the marker
-                // 2. End of string OR underscore OR capital letter after the marker
-                const hasStartBoundary = markerIndex === 0 ||
-                    preMarkerPrefix === '_' ||
-                    /[A-Z]/.test(preMarkerPrefix) ||
-                    /[A-Z]/.test(variableName[markerIndex]);
-                const hasEndBoundary = markerIndex + normalizedMarker.length === normalizedVarName.length ||
-                    suffix === '_' ||
-                    /[A-Z]/.test(suffix);
-                return hasStartBoundary && hasEndBoundary;
+                // Full type-word markers (non-abbreviations: String, Number, Function,
+                // Array, Object, Boolean, …) are Hungarian only when they occupy the
+                // first or last camelCase segment — a genuine prefix or suffix that
+                // tags the entity's runtime type. The prefix/suffix character checks
+                // above already return `true` for those positions, so reaching this
+                // point means the marker sits in a middle segment of the identifier
+                // (e.g. cloud·Function·Registry, user·String·Name). A middle
+                // full-type-word qualifies a domain concept ("a registry of cloud
+                // functions") rather than redundantly encoding the entity's type.
+                // Accepting the resulting false negatives is the deliberate trade-off:
+                // middle-segment full-type-words are overwhelmingly domain vocabulary,
+                // not type tags.
+                return false;
             });
         }
         // Check if the identifier is a built-in method or imported from an external module

package/lib/rules/no-type-assertion-returns.js

@@ -177,9 +177,13 @@ exports.noTypeAssertionReturns = (0, createRule_1.createRule)({
             if (node.parent?.type === utils_1.AST_NODE_TYPES.LogicalExpression) {
                 return true;
             }
-            // Allow type assertions within method calls like array.includes()
-            if (node.parent?.type === utils_1.AST_NODE_TYPES.CallExpression &&
-                node.parent.callee.type === utils_1.AST_NODE_TYPES.MemberExpression) {
+            // Allow type assertions that are direct arguments of any call or new expression.
+            // The asserted value is an argument — TypeScript structurally checks it against the
+            // parameter type — so the returned value is the call's result, not the cast itself.
+            // This covers method calls (obj.method(x as T)), plain calls (fn(x as T)), and
+            // constructors (new Ctor(x as T)) uniformly.
+            if (node.parent?.type === utils_1.AST_NODE_TYPES.CallExpression ||
+                node.parent?.type === utils_1.AST_NODE_TYPES.NewExpression) {
                 return true;
             }
             // Allow type assertions within array includes checks
@@ -195,27 +199,6 @@ exports.noTypeAssertionReturns = (0, createRule_1.createRule)({
             if (isPropertyAccess(node) && isInsideConditionalStatement(node)) {
                 return true;
             }
-            // Allow type assertions in object instantiations (as constructor arguments)
-            if (node.parent?.type === utils_1.AST_NODE_TYPES.ObjectExpression &&
-                node.parent.parent?.type === utils_1.AST_NODE_TYPES.NewExpression) {
-                return true;
-            }
-            // Allow type assertions as arguments to constructors
-            if (node.parent?.type === utils_1.AST_NODE_TYPES.NewExpression ||
-                (node.parent?.type === utils_1.AST_NODE_TYPES.CallExpression &&
-                    node.parent.parent?.type === utils_1.AST_NODE_TYPES.NewExpression)) {
-                return true;
-            }
-            // Allow type assertions as arguments to constructor calls
-            if (node.parent?.type === utils_1.AST_NODE_TYPES.CallExpression) {
-                let current = node.parent;
-                while (current?.parent) {
-                    if (current.parent.type === utils_1.AST_NODE_TYPES.NewExpression) {
-                        return true;
-                    }
-                    current = current.parent;
-                }
-            }
             // Allow type assertions in JSX attributes/props or object properties
             if (isInsideJSXAttributeOrObjectProperty(node)) {
                 return true;

package/lib/rules/no-unnecessary-verb-suffix.js

@@ -59,9 +59,6 @@ const COMMON_PREPOSITION_SUFFIXES = new Set([
     'Where',
     'When',
     'While',
-    // Programming-specific suffixes
-    'Async',
-    'Sync',
 ]);
 /**
  * Phrasal-verb particles that fuse with a preceding past participle to form an

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

@@ -485,6 +485,98 @@ function isStyleJSXAttributeValue(node) {
     }
     return false;
 }
+/**
+ * Returns true when the node is a JSX element or fragment. JSX nodes are
+ * always fresh references each render — wrapping a containing literal in
+ * useMemo provides no referential-stability benefit because the JSX member
+ * changes on every call regardless of the wrapper.
+ */
+function isJSXNode(node) {
+    return (node.type === utils_1.AST_NODE_TYPES.JSXElement ||
+        node.type === utils_1.AST_NODE_TYPES.JSXFragment);
+}
+/**
+ * Collects the names of variables declared in the owning function's top-level
+ * block body whose initializers resolve to JSX elements or fragments. Used to
+ * detect shorthand object properties like `{ Portal }` where
+ * `const Portal = <div />` precedes the return statement.
+ *
+ * Only top-level declarations are scanned; inner function scopes have their
+ * own render lifecycles and are not candidates for this exemption.
+ */
+function collectLocalJSXBindings(owner) {
+    const bindings = new Set();
+    const body = owner.body;
+    if (body.type !== utils_1.AST_NODE_TYPES.BlockStatement)
+        return bindings;
+    for (const stmt of body.body) {
+        if (stmt.type !== utils_1.AST_NODE_TYPES.VariableDeclaration)
+            continue;
+        for (const declarator of stmt.declarations) {
+            if (declarator.id.type !== utils_1.AST_NODE_TYPES.Identifier)
+                continue;
+            if (!declarator.init)
+                continue;
+            const unwrapped = unwrapNestedExpressions(declarator.init);
+            if (isJSXNode(unwrapped)) {
+                bindings.add(declarator.id.name);
+            }
+        }
+    }
+    return bindings;
+}
+/**
+ * Returns true when an ObjectExpression returned from a hook contains at
+ * least one property whose value is a JSX element or fragment — either
+ * directly inline (`{ Portal: <div /> }`) or via a shorthand identifier
+ * (`{ Portal }`) that resolves to a JSX initializer in the same function
+ * scope. Such objects cannot be stabilised by wrapping them in useMemo
+ * because the JSX member is a fresh reference on every render regardless of
+ * the wrapper. This is the same "no stability benefit" rationale applied to
+ * sx/style JSX attribute values.
+ */
+function objectLiteralContainsJSXValue(node, owner) {
+    // Resolve shorthand bindings lazily — only when at least one shorthand
+    // property is present, to avoid the body scan for the common inline case.
+    let localJSXBindings = null;
+    for (const prop of node.properties) {
+        if (prop.type === utils_1.AST_NODE_TYPES.SpreadElement)
+            continue;
+        const value = unwrapNestedExpressions(prop.value);
+        // Direct inline JSX: { Portal: <div /> } or { el: <></> }
+        if (isJSXNode(value)) {
+            return true;
+        }
+        // Shorthand identifier: { Portal } — resolve to a local JSX binding.
+        if (prop.shorthand && value.type === utils_1.AST_NODE_TYPES.Identifier) {
+            if (!localJSXBindings) {
+                localJSXBindings = collectLocalJSXBindings(owner);
+            }
+            if (localJSXBindings.has(value.name)) {
+                return true;
+            }
+        }
+    }
+    return false;
+}
+/**
+ * Returns true when an ArrayExpression returned from a hook contains at least
+ * one element that is a JSX element or fragment (after unwrapping expression
+ * wrappers). The same "no stability benefit" rationale applies: a JSX element
+ * is a fresh reference each render, so wrapping the array in useMemo would
+ * recompute on every call without improving referential stability.
+ */
+function arrayLiteralContainsJSXValue(node) {
+    for (const element of node.elements) {
+        if (!element)
+            continue;
+        const unwrapped = unwrapNestedExpressions(element);
+        if (isJSXNode(unwrapped)) {
+            return true;
+        }
+    }
+    return false;
+}
 /**
  * Formats a readable label for diagnostics based on the owning function.
  * @param fn Owning component or hook function.
@@ -511,7 +603,7 @@ exports.reactMemoizeLiterals = (0, createRule_1.createRule)({
         messages: {
             componentLiteral: 'New {{literalType}} inside {{context}} is created on every render → Breaks referential stability for hooks/props and can re-run effects or re-render children → Hoist it to a module-level constant or wrap it in {{memoHook}} with the right dependencies.',
             nestedHookLiteral: 'Nested {{literalType}} inside {{hookName}} arguments is recreated on every render → Dependency/reference comparisons change each time and defeat memoization/caching → Extract it into a memoized value (useMemo/useCallback) or hoist it to a module constant before passing it to {{hookName}}.',
-            hookReturnLiteral: '{{hookName}} returns a {{literalType}} literal on each render → Callers receive a fresh reference and may re-render or re-run effects → Memoize the returned value with useMemo/useCallback or return pre-memoized pieces so callers see stable references.',
+            hookReturnLiteral: '{{hookName}} returns an {{literalType}} on each render → Callers receive a fresh reference and may re-render or re-run effects → Memoize the returned value with useMemo/useCallback or return pre-memoized pieces so callers see stable references.',
             memoizeLiteralSuggestion: 'This {{literalType}} is created inline → It produces a new reference each render → Wrap it in {{memoHook}} and include every closed-over value in the dependency array.',
         },
     },
@@ -659,6 +751,19 @@ exports.reactMemoizeLiterals = (0, createRule_1.createRule)({
                 return;
             }
             if (isReturnValueFromHook(node, owner)) {
+                // A returned literal whose members include a JSX element or fragment
+                // cannot be stabilised by useMemo: JSX nodes are inherently fresh
+                // references each render, so the wrapper recomputes every call
+                // regardless. This mirrors the "no stability benefit" carve-out for
+                // sx/style JSX attribute values (see isStyleJSXAttributeValue).
+                if (node.type === utils_1.AST_NODE_TYPES.ObjectExpression &&
+                    objectLiteralContainsJSXValue(node, owner)) {
+                    return;
+                }
+                if (node.type === utils_1.AST_NODE_TYPES.ArrayExpression &&
+                    arrayLiteralContainsJSXValue(node)) {
+                    return;
+                }
                 const hookName = getFunctionName(owner) ?? 'this hook';
                 context.report({
                     node,

package/package.json

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

package/release-manifest.json

@@ -1,4 +1,64 @@
 [
+  {
+    "version": "1.17.2",
+    "date": "2026-07-02T12:29:19.590Z",
+    "rules": [
+      {
+        "name": "no-explicit-return-type",
+        "changeType": "fix",
+        "issues": [
+          1253
+        ],
+        "summary": "exempt read-only widening return types from removal (closes #1253)"
+      },
+      {
+        "name": "no-hungarian",
+        "changeType": "fix",
+        "issues": [
+          1255
+        ],
+        "summary": "treat Fn/Func/Function as function-role designators, not type tags (closes #1255)"
+      },
+      {
+        "name": "no-type-assertion-returns",
+        "changeType": "fix",
+        "issues": [
+          1254
+        ],
+        "summary": "allow type assertions as call/new arguments in return position (closes #1254)"
+      },
+      {
+        "name": "no-unnecessary-verb-suffix",
+        "changeType": "fix",
+        "issues": [
+          1252
+        ],
+        "summary": "stop flagging Async/Sync execution-model suffixes (closes #1252)"
+      }
+    ]
+  },
+  {
+    "version": "1.17.1",
+    "date": "2026-07-01T22:31:34.840Z",
+    "rules": [
+      {
+        "name": "no-hungarian",
+        "changeType": "fix",
+        "issues": [
+          1250
+        ],
+        "summary": "exempt middle-segment full-type-words from Hungarian detection (closes #1250)"
+      },
+      {
+        "name": "react-memoize-literals",
+        "changeType": "fix",
+        "issues": [
+          1251
+        ],
+        "summary": "exempt hook returns containing JSX-valued members (closes #1251)"
+      }
+    ]
+  },
   {
     "version": "1.17.0",
     "date": "2026-07-01T05:16:18.225Z",