@blumintinc/eslint-plugin-blumint 1.19.1 → 1.19.3

package/lib/index.js

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

package/lib/rules/prefer-utility-function-own-file.d.ts

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

package/lib/rules/prefer-utility-function-own-file.js

@@ -186,12 +186,42 @@ function countStatements(fn) {
     return 1;
 }
 /**
- * Counts the number of source lines spanned by a function node.
+ * Counts the number of significant source lines spanned by a function node —
+ * lines that carry actual code. Blank lines and comment-only lines are ignored
+ * so a function's "size" does not depend on how heavily it is commented:
+ * identical code with and without JSDoc/inline comments lints identically.
  */
-function countLines(fn) {
+function countLines(fn, sourceCode) {
     if (!fn.loc)
         return 0;
-    return fn.loc.end.line - fn.loc.start.line + 1;
+    const startLine = fn.loc.start.line;
+    const endLine = fn.loc.end.line;
+    const lines = sourceCode.lines;
+    let count = 0;
+    for (let line = startLine; line <= endLine; line++) {
+        const text = lines[line - 1] ?? '';
+        if (text.trim() === '')
+            continue;
+        // Blank out any character ranges on this line covered by a comment, then
+        // check whether any non-whitespace code remains.
+        const chars = text.split('');
+        for (const comment of sourceCode.getAllComments()) {
+            if (!comment.loc)
+                continue;
+            if (comment.loc.start.line > line || comment.loc.end.line < line) {
+                continue;
+            }
+            const from = comment.loc.start.line === line ? comment.loc.start.column : 0;
+            const to = comment.loc.end.line === line ? comment.loc.end.column : chars.length;
+            for (let col = from; col < to && col < chars.length; col++) {
+                chars[col] = ' ';
+            }
+        }
+        if (chars.join('').trim() === '')
+            continue;
+        count++;
+    }
+    return count;
 }
 /**
  * Returns the function expression node if the VariableDeclarator initializer
@@ -331,11 +361,19 @@ exports.preferUtilityFunctionOwnFile = (0, createRule_1.createRule)({
         const minLines = options.minLines ?? DEFAULT_MIN_LINES;
         const ignoreClosures = options.ignoreClosures ?? DEFAULT_IGNORE_CLOSURES;
         const filename = context.getFilename();
+        const sourceCode = context.getSourceCode();
         // Exempt test/mock/type files entirely
         if (isExemptFile(filename))
             return {};
         const basename = fileBasename(filename);
         const topLevelFunctions = [];
+        // Top-level `VariableDeclarator` initializer expressions that are NOT
+        // themselves functions — e.g. a `Record` registry object literal or an
+        // array literal whose entries invoke a factory helper. These are the
+        // sibling consumers a reverse-closure walk over function bodies alone would
+        // miss, so we retain them to complete the "does the file need the
+        // candidate?" check.
+        const nonFunctionInitializers = [];
         let hasExportDefault = false;
         // Names of every top-level binding (functions, consts, lets, destructured
         // bindings). Used by the closure exemption: a function that references any
@@ -447,8 +485,14 @@ exports.preferUtilityFunctionOwnFile = (0, createRule_1.createRule)({
                         continue;
                     const name = declarator.id.name;
                     const fn = extractFunctionInit(declarator.init);
-                    if (!fn)
+                    if (!fn) {
+                        // A non-function initializer (object/array literal, call, etc.) may
+                        // still consume a sibling helper by name; retain it for the
+                        // reverse-closure exemption.
+                        if (declarator.init)
+                            nonFunctionInitializers.push(declarator.init);
                         continue;
+                    }
                     topLevelFunctions.push({
                         node: declarator,
                         name,
@@ -515,7 +559,7 @@ exports.preferUtilityFunctionOwnFile = (0, createRule_1.createRule)({
                     // (already covered above, but be explicit)
                     // --- Size check: must be sizable ---
                     const stmts = countStatements(fn);
-                    const lines = countLines(fn);
+                    const lines = countLines(fn, sourceCode);
                     const isSizable = stmts >= minStatements || lines >= minLines;
                     if (!isSizable)
                         continue;
@@ -524,6 +568,12 @@ exports.preferUtilityFunctionOwnFile = (0, createRule_1.createRule)({
                         const closesOverModuleScope = functionClosesOverModuleScope(fn, topLevelBindingNames);
                         if (closesOverModuleScope)
                             continue;
+                        // Reverse-closure exemption: the candidate is the shared internal
+                        // primitive its sibling exports build on. A cohesive multi-export
+                        // utility module is already a utility file; extracting its core
+                        // would sever the file's internal cohesion.
+                        if (isReferencedBySibling(info, topLevelFunctions, nonFunctionInitializers))
+                            continue;
                     }
                     // --- Co-location gate: file must have a distinct primary export ---
                     // The file has a distinct primary purpose if:
@@ -580,6 +630,43 @@ function functionClosesOverModuleScope(fn, topLevelBindingNames) {
     }
     return false;
 }
+/**
+ * Returns true if any *other* top-level sibling in the file references the
+ * candidate by name. When sibling exports build on the candidate, the candidate
+ * is the module's shared internal primitive — a cohesive multi-export utility
+ * module is already a utility file, and extracting its core would orphan the
+ * siblings from the primitive they depend on.
+ *
+ * Two kinds of sibling can consume the candidate:
+ * - Another top-level function that references it in its body.
+ * - A non-function top-level initializer expression that references it — e.g. a
+ *   `Record` registry object literal or array literal whose entries invoke the
+ *   candidate factory (`export const RENDERERS = { b: buildRenderer('b') }`).
+ *   The function-body walk cannot see these, so the initializer expressions are
+ *   inspected directly.
+ *
+ * This is the mirror of the closure exemption: `functionClosesOverModuleScope`
+ * asks "does the candidate need the file?"; this asks "does the file need the
+ * candidate?". Either direction of dependency means extraction severs cohesion.
+ */
+function isReferencedBySibling(candidate, allFunctions, nonFunctionInitializers = []) {
+    for (const other of allFunctions) {
+        if (other.name === candidate.name)
+            continue;
+        const body = getFunctionBody(other.fn);
+        if (!body)
+            continue;
+        const refs = collectReferencedIdentifiers(body);
+        if (refs.has(candidate.name))
+            return true;
+    }
+    for (const init of nonFunctionInitializers) {
+        const refs = collectReferencedIdentifiers(init);
+        if (refs.has(candidate.name))
+            return true;
+    }
+    return false;
+}
 /**
  * Determines whether the file has a distinct primary purpose (co-location gate).
  * A file has a distinct primary purpose if (excluding the function under test):

package/lib/rules/vertically-group-related-functions.js

@@ -259,6 +259,12 @@ function dependencyOrder(functions, direction, groupOrder) {
         });
     });
     const roots = namesInTiebreakOrder.filter((name) => (incomingCount.get(name) || 0) === 0);
+    // Remaining unemitted callers per function, seeded from incomingCount. Used
+    // (callers-first only) to defer a shared callee until every caller that
+    // reaches it has been emitted, so the shared primitive lands below all of its
+    // callers rather than being greedily inlined beneath whichever caller the DFS
+    // reaches first — which would place its other callers below their own helper.
+    const remainingCallers = new Map(incomingCount);
     const visit = (name) => {
         if (visited.has(name)) {
             return;
@@ -271,7 +277,18 @@ function dependencyOrder(functions, direction, groupOrder) {
         }
         else {
             order.push(name);
-            deps.forEach(visit);
+            for (const dep of deps) {
+                const remaining = (remainingCallers.get(dep) ?? 0) - 1;
+                remainingCallers.set(dep, remaining);
+                // Descend into the callee only once its last caller has been emitted.
+                // A shared callee is deferred here and picked up when the caller that
+                // drives its counter to zero recurses into it. If a callee is never
+                // driven to zero (e.g. a dependency cycle), the top-level sweep below
+                // still visits it, so no function is dropped from the order.
+                if (remaining <= 0) {
+                    visit(dep);
+                }
+            }
         }
     };
     // Depth-first from roots keeps each caller immediately above its own helper

package/package.json

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

package/release-manifest.json

@@ -1,4 +1,40 @@
 [
+  {
+    "version": "1.19.3",
+    "date": "2026-07-14T11:28:07.708Z",
+    "rules": [
+      {
+        "name": "prefer-utility-function-own-file",
+        "changeType": "fix",
+        "issues": [
+          1305
+        ],
+        "summary": "exempt factory consumed only by sibling const initializer literal (closes #1305)"
+      }
+    ]
+  },
+  {
+    "version": "1.19.2",
+    "date": "2026-07-14T07:32:08.575Z",
+    "rules": [
+      {
+        "name": "prefer-utility-function-own-file",
+        "changeType": "fix",
+        "issues": [
+          1303
+        ],
+        "summary": "exempt shared primitive of cohesive multi-export utility modules (closes #1303)"
+      },
+      {
+        "name": "vertically-group-related-functions",
+        "changeType": "fix",
+        "issues": [
+          1304
+        ],
+        "summary": "defer shared callees until all callers emitted (closes #1304)"
+      }
+    ]
+  },
   {
     "version": "1.19.1",
     "date": "2026-07-14T01:28:36.352Z",