@blumintinc/eslint-plugin-blumint 1.17.1 → 1.17.3

package/lib/index.js

@@ -217,7 +217,7 @@ function noFrontendImportsFromFunctionsPatterns(pattern) {
 module.exports = {
     meta: {
         name: '@blumintinc/eslint-plugin-blumint',
-        version: '1.17.1',
+        version: '1.17.3',
     },
     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) {

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
@@ -134,6 +131,41 @@ function isPhrasalVerbEnding(name, suffix) {
     const lastWord = beforeSuffix.match(/[A-Z]?[a-z]+$/)?.[0] ?? '';
     return phrasalVerbStem(lastWord) !== null;
 }
+/**
+ * Returns true when `node` (or its relevant ancestor for the declaration kind)
+ * is directly wrapped in an export declaration. An exported symbol must not be
+ * auto-fixed because the fixer can only rename within the current file, leaving
+ * cross-file import references broken.
+ *
+ * Call this with:
+ *  - the FunctionDeclaration node for `function foo() {}`
+ *  - the ArrowFunctionExpression/FunctionExpression node for `const foo = () => {}`
+ *    (its parent chain: arrow → VariableDeclarator → VariableDeclaration → export?)
+ */
+function isExported(node) {
+    const parent = node.parent;
+    if (!parent)
+        return false;
+    // FunctionDeclaration directly inside `export function foo() {}`
+    if (parent.type === utils_1.AST_NODE_TYPES.ExportNamedDeclaration ||
+        parent.type === utils_1.AST_NODE_TYPES.ExportDefaultDeclaration) {
+        return true;
+    }
+    // Arrow/FunctionExpression assigned to a VariableDeclarator:
+    //   VariableDeclarator → VariableDeclaration → ExportNamedDeclaration
+    if (parent.type === utils_1.AST_NODE_TYPES.VariableDeclarator) {
+        const varDecl = parent.parent; // VariableDeclaration
+        if (!varDecl)
+            return false;
+        const varDeclParent = varDecl.parent; // possible ExportNamedDeclaration
+        if (varDeclParent &&
+            (varDeclParent.type === utils_1.AST_NODE_TYPES.ExportNamedDeclaration ||
+                varDeclParent.type === utils_1.AST_NODE_TYPES.ExportDefaultDeclaration)) {
+            return true;
+        }
+    }
+    return false;
+}
 exports.noUnnecessaryVerbSuffix = (0, createRule_1.createRule)({
     name: 'no-unnecessary-verb-suffix',
     meta: {
@@ -150,7 +182,27 @@ exports.noUnnecessaryVerbSuffix = (0, createRule_1.createRule)({
     },
     defaultOptions: [],
     create(context) {
-        function checkFunctionName(node, name) {
+        function checkFunctionName(node, name, 
+        /**
+         * The AST node that holds the identifier being renamed.
+         * For FunctionDeclaration this is `node.id`; for VariableDeclarator
+         * assigned arrows it is `declarator.id`; for Property/MethodDefinition
+         * it is the key node. Passing it explicitly avoids re-deriving it inside
+         * the fixer and allows the reference-rename loop to skip it cleanly.
+         */
+        declarationIdNode, 
+        /**
+         * The AST node whose declared variables the scope manager tracks.
+         * For FunctionDeclaration this is `node` itself; for a VariableDeclarator
+         * arrow it is the VariableDeclarator; for methods/properties it is null
+         * because member references are not in scope (resolved via `this.x`).
+         */
+        scopeNode, 
+        /**
+         * Whether the symbol is exported. When true, the fix is suppressed so we
+         * don't produce broken cross-file renames.
+         */
+        exported) {
             if (!name)
                 return;
             for (const suffix of COMMON_PREPOSITION_SUFFIXES) {
@@ -182,25 +234,50 @@ exports.noUnnecessaryVerbSuffix = (0, createRule_1.createRule)({
                                 suggestion,
                             },
                             fix(fixer) {
-                                if (node.type === utils_1.AST_NODE_TYPES.FunctionDeclaration) {
-                                    return fixer.replaceText(node.id, suggestion);
+                                // An autofix here is only reference-safe when the fixer can
+                                // rename EVERY use of the symbol, not just its declaration —
+                                // otherwise call sites are orphaned and produce a ReferenceError
+                                // (#1256). Two cases make that impossible, so the fix is
+                                // suppressed (report only, no `--fix` change):
+                                //
+                                //  1. Exported symbols — a single-file fixer cannot reach
+                                //     cross-file import references.
+                                //  2. Member-accessed symbols (class methods, object-literal
+                                //     properties, interface method signatures) — their call
+                                //     sites are member expressions (`this.x()`, `obj.x()`) that
+                                //     the scope manager does not track as variable references,
+                                //     so they cannot be found and renamed syntactically.
+                                //     `scopeNode` is null for exactly these declarations.
+                                if (exported || !scopeNode || !declarationIdNode) {
+                                    return null;
                                 }
-                                else if (node.type === utils_1.AST_NODE_TYPES.ArrowFunctionExpression ||
-                                    node.type === utils_1.AST_NODE_TYPES.FunctionExpression) {
-                                    const parent = node.parent;
-                                    if (parent &&
-                                        (parent.type === utils_1.AST_NODE_TYPES.VariableDeclarator ||
-                                            parent.type === utils_1.AST_NODE_TYPES.Property ||
-                                            parent.type === utils_1.AST_NODE_TYPES.MethodDefinition)) {
-                                        if ('key' in parent) {
-                                            return fixer.replaceText(parent.key, suggestion);
-                                        }
-                                        else if ('id' in parent && parent.id) {
-                                            return fixer.replaceText(parent.id, suggestion);
-                                        }
+                                // Scope-tracked symbols (FunctionDeclaration, VariableDeclarator
+                                // arrows/functions, named FunctionExpression): rename the
+                                // declaration identifier and every in-file reference together so
+                                // no call site is left pointing at the old name.
+                                const fixes = [
+                                    fixer.replaceText(declarationIdNode, suggestion),
+                                ];
+                                // Note: context.getDeclaredVariables is the API available in the
+                                // pinned @typescript-eslint version (the SourceCode-based
+                                // replacement is not yet in these type definitions).
+                                const declaredVars = context.getDeclaredVariables(scopeNode);
+                                // getDeclaredVariables returns ALL variables the node declares
+                                // (e.g. for a FunctionDeclaration it includes the function name
+                                // variable AND its parameter variables). Filter to the one whose
+                                // name matches the symbol being renamed so we only follow
+                                // references to the name, not parameters.
+                                for (const variable of declaredVars) {
+                                    if (variable.name !== name)
+                                        continue;
+                                    for (const ref of variable.references) {
+                                        // Skip the declaration identifier itself — already handled.
+                                        if (ref.identifier === declarationIdNode)
+                                            continue;
+                                        fixes.push(fixer.replaceText(ref.identifier, suggestion));
                                     }
                                 }
-                                return null;
+                                return fixes;
                             },
                         });
                     }
@@ -210,38 +287,49 @@ exports.noUnnecessaryVerbSuffix = (0, createRule_1.createRule)({
         return {
             FunctionDeclaration(node) {
                 if (node.id) {
-                    checkFunctionName(node, node.id.name);
+                    checkFunctionName(node, node.id.name, node.id, node, isExported(node));
                 }
             },
             VariableDeclarator(node) {
                 if (node.id.type === utils_1.AST_NODE_TYPES.Identifier &&
                     (node.init?.type === utils_1.AST_NODE_TYPES.ArrowFunctionExpression ||
                         node.init?.type === utils_1.AST_NODE_TYPES.FunctionExpression)) {
-                    checkFunctionName(node.init, node.id.name);
+                    checkFunctionName(node.init, node.id.name, node.id, node, isExported(node.init));
                 }
             },
             MethodDefinition(node) {
                 if (node.key.type === utils_1.AST_NODE_TYPES.Identifier) {
-                    checkFunctionName(node.value, node.key.name);
+                    // Class methods are called via member expressions (`this.method()`,
+                    // `instance.method()`) that the scope manager does not track as
+                    // references. A syntactic single-file fixer therefore cannot find and
+                    // rename those call sites, so renaming the method would orphan them
+                    // (#1256). Pass null for both the rename target and scopeNode so the
+                    // violation is still reported but no unsafe fix is offered.
+                    checkFunctionName(node.value, node.key.name, null, null, false);
                 }
             },
             TSMethodSignature(node) {
-                // Handle interface method signatures
+                // Interface method signatures have their implementations and call sites
+                // elsewhere (member accesses on implementers), unreachable from this
+                // declaration. Report only — never offer a rename fix.
                 if (node.key.type === utils_1.AST_NODE_TYPES.Identifier) {
-                    checkFunctionName(node, node.key.name);
+                    checkFunctionName(node, node.key.name, null, null, false);
                 }
             },
             Property(node) {
                 if (node.key.type === utils_1.AST_NODE_TYPES.Identifier &&
                     (node.value.type === utils_1.AST_NODE_TYPES.ArrowFunctionExpression ||
                         node.value.type === utils_1.AST_NODE_TYPES.FunctionExpression)) {
-                    checkFunctionName(node.value, node.key.name);
+                    // Object-literal method properties are accessed via member expressions
+                    // (`obj.method()`) the scope manager does not track. As with class
+                    // methods, the fix is suppressed to avoid orphaning call sites.
+                    checkFunctionName(node.value, node.key.name, null, null, false);
                 }
             },
             FunctionExpression(node) {
                 // Handle named function expressions
                 if (node.id) {
-                    checkFunctionName(node, node.id.name);
+                    checkFunctionName(node, node.id.name, node.id, node, isExported(node));
                 }
             },
         };

package/package.json

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

package/release-manifest.json

@@ -1,4 +1,56 @@
 [
+  {
+    "version": "1.17.3",
+    "date": "2026-07-02T16:07:25.816Z",
+    "rules": [
+      {
+        "name": "no-unnecessary-verb-suffix",
+        "changeType": "fix",
+        "issues": [
+          1256
+        ],
+        "summary": "make autofix reference-safe (closes #1256)"
+      }
+    ]
+  },
+  {
+    "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",