@blumintinc/eslint-plugin-blumint 1.18.10 → 1.18.12

package/lib/index.js

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

package/lib/rules/parallelize-async-operations.js

@@ -170,6 +170,42 @@ exports.parallelizeAsyncOperations = (0, createRule_1.createRule)({
          * unrelated managers, but errs on the side of safety.
          */
         const COORDINATOR_PATTERN = /batch|manager|collector|transaction|tx|coordinator|unitofwork|accumulator|aggregator/i;
+        /**
+         * Matches guard/assertion callees by their leading verb. Anchored at the
+         * start so it fires on the callee's own verb (assertStartable,
+         * validateInput, ensureExists, requireAuth, checkAccess, verifyOwnership,
+         * guardAgainstX) rather than on an arbitrary substring elsewhere in the
+         * name.
+         */
+        const GUARD_PATTERN = /^(assert|ensure|require|validate|verify|guard|check)/i;
+        /**
+         * Extracts the callee's method name (the identifier bearing the leading
+         * verb) from an await expression argument. Handles both direct
+         * CallExpressions and optional-call ChainExpressions, and both bare
+         * identifier callees and member-expression callees.
+         */
+        function getCalleeMethodName(awaitExpr) {
+            let callExpr = null;
+            if (awaitExpr.argument.type === utils_1.AST_NODE_TYPES.CallExpression) {
+                callExpr = awaitExpr.argument;
+            }
+            else if (awaitExpr.argument.type === utils_1.AST_NODE_TYPES.ChainExpression &&
+                awaitExpr.argument.expression.type === utils_1.AST_NODE_TYPES.CallExpression) {
+                callExpr = awaitExpr.argument.expression;
+            }
+            if (!callExpr) {
+                return null;
+            }
+            const callee = callExpr.callee;
+            if (callee.type === utils_1.AST_NODE_TYPES.MemberExpression &&
+                callee.property.type === utils_1.AST_NODE_TYPES.Identifier) {
+                return callee.property.name;
+            }
+            if (callee.type === utils_1.AST_NODE_TYPES.Identifier) {
+                return callee.name;
+            }
+            return null;
+        }
         /**
          * Checks if there are dependencies between await expressions
          */
@@ -214,28 +250,34 @@ exports.parallelizeAsyncOperations = (0, createRule_1.createRule)({
                 }
                 // 3. Check for operations that might have side effects
                 // If any node has a side effect, we should not parallelize the sequence
-                let callExpr = null;
-                if (awaitExpr.argument.type === utils_1.AST_NODE_TYPES.CallExpression) {
-                    callExpr = awaitExpr.argument;
+                const methodName = getCalleeMethodName(awaitExpr);
+                if (methodName &&
+                    sideEffectPatterns.some((pattern) => pattern.test(methodName))) {
+                    return true;
                 }
-                else if (awaitExpr.argument.type === utils_1.AST_NODE_TYPES.ChainExpression &&
-                    awaitExpr.argument.expression.type === utils_1.AST_NODE_TYPES.CallExpression) {
-                    callExpr = awaitExpr.argument.expression;
+            }
+            // 4. Guard-then-side-effect ordering barrier. A discarded-result await
+            // whose callee reads as a guard/assertion (assert*, ensure*, validate*,
+            // ...) is a control-flow gate: it throws to abort the run when its
+            // precondition fails, so any await after it must run ONLY if the guard
+            // resolves. Promise.all invokes every operand eagerly, so it would fire
+            // the gated side effect even when the guard rejects. Treat the guard's
+            // presence (when something follows it) as a sequencing dependency that
+            // blocks parallelizing the whole run. Only discarded-result awaits
+            // (ExpressionStatements) qualify; `const ok = await validate(x)` has a
+            // variable and is handled by the data-dependency path above.
+            for (let i = 0; i < awaitNodes.length - 1; i++) {
+                const node = awaitNodes[i];
+                if (node.type !== utils_1.AST_NODE_TYPES.ExpressionStatement) {
+                    continue;
                 }
-                if (callExpr) {
-                    const callee = callExpr.callee;
-                    let methodName = null;
-                    if (callee.type === utils_1.AST_NODE_TYPES.MemberExpression &&
-                        callee.property.type === utils_1.AST_NODE_TYPES.Identifier) {
-                        methodName = callee.property.name;
-                    }
-                    else if (callee.type === utils_1.AST_NODE_TYPES.Identifier) {
-                        methodName = callee.name;
-                    }
-                    if (methodName &&
-                        sideEffectPatterns.some((pattern) => pattern.test(methodName))) {
-                        return true;
-                    }
+                const awaitExpr = getAwaitExpression(node);
+                if (!awaitExpr) {
+                    continue;
+                }
+                const methodName = getCalleeMethodName(awaitExpr);
+                if (methodName && GUARD_PATTERN.test(methodName)) {
+                    return true;
                 }
             }
             // If any node is a variable declaration with destructuring, consider it as having dependencies

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

@@ -53,6 +53,8 @@ function collectReferencedIdentifiers(node) {
                 // Record parameter names as locals
                 for (const param of fn.params) {
                     collectPatternNames(param, locals);
+                    // Default values inside a parameter pattern may reference module scope
+                    walkPatternDefaults(param);
                 }
                 walk(fn.body);
                 break;
@@ -60,6 +62,10 @@ function collectReferencedIdentifiers(node) {
             case utils_1.AST_NODE_TYPES.VariableDeclarator: {
                 const decl = n;
                 collectPatternNames(decl.id, locals);
+                // Default values inside a destructuring pattern may reference module
+                // scope (e.g. `const { runner = runCli } = props`) — the binding names
+                // are locals, but the default expressions are real references.
+                walkPatternDefaults(decl.id);
                 walk(decl.init);
                 break;
             }
@@ -83,6 +89,40 @@ function collectReferencedIdentifiers(node) {
             }
         }
     }
+    // Walks only the right-hand sides of AssignmentPattern defaults nested inside
+    // a binding pattern. The binding names themselves are locals; their defaults
+    // are ordinary references that `walk` (which skips patterns via the dedicated
+    // VariableDeclarator/function cases) would otherwise never visit.
+    function walkPatternDefaults(p) {
+        if (!p)
+            return;
+        switch (p.type) {
+            case utils_1.AST_NODE_TYPES.AssignmentPattern:
+                walk(p.right);
+                walkPatternDefaults(p.left);
+                break;
+            case utils_1.AST_NODE_TYPES.ArrayPattern:
+                for (const el of p.elements) {
+                    walkPatternDefaults(el);
+                }
+                break;
+            case utils_1.AST_NODE_TYPES.ObjectPattern:
+                for (const prop of p.properties) {
+                    if (prop.type === utils_1.AST_NODE_TYPES.RestElement) {
+                        walkPatternDefaults(prop.argument);
+                    }
+                    else {
+                        walkPatternDefaults(prop.value);
+                    }
+                }
+                break;
+            case utils_1.AST_NODE_TYPES.RestElement:
+                walkPatternDefaults(p.argument);
+                break;
+            default:
+                break;
+        }
+    }
     walk(node);
     // Remove purely local names from the reference set
     for (const local of locals) {
@@ -219,6 +259,38 @@ function isExemptFile(filename) {
         return true;
     return false;
 }
+/**
+ * Returns true if the module top-level self-invokes one of its own functions,
+ * e.g. `void autoRunIfMain();` or `main();`. This is the signature of a CLI
+ * entry-point module whose colocated helpers ARE its purpose, not foreign
+ * utilities that should be extracted.
+ */
+function hasTopLevelSelfInvocation(program, topLevelFunctionNames) {
+    for (const statement of program.body) {
+        if (statement.type !== utils_1.AST_NODE_TYPES.ExpressionStatement)
+            continue;
+        // Unwrap `void expr`, `await expr`, and parenthesized wrappers to reach the
+        // underlying call (e.g. `void autoRunIfMain();`).
+        let expr = statement.expression;
+        while (expr &&
+            ((expr.type === utils_1.AST_NODE_TYPES.UnaryExpression &&
+                expr.operator === 'void') ||
+                expr.type === utils_1.AST_NODE_TYPES.AwaitExpression ||
+                expr.type === 'ParenthesizedExpression')) {
+            expr =
+                expr.argument ??
+                    expr.expression;
+        }
+        if (!expr || expr.type !== utils_1.AST_NODE_TYPES.CallExpression)
+            continue;
+        const callee = expr.callee;
+        if (callee.type === utils_1.AST_NODE_TYPES.Identifier &&
+            topLevelFunctionNames.has(callee.name)) {
+            return true;
+        }
+    }
+    return false;
+}
 exports.preferUtilityFunctionOwnFile = (0, createRule_1.createRule)({
     name: 'prefer-utility-function-own-file',
     meta: {
@@ -265,6 +337,12 @@ exports.preferUtilityFunctionOwnFile = (0, createRule_1.createRule)({
         const basename = fileBasename(filename);
         const topLevelFunctions = [];
         let hasExportDefault = false;
+        // Names of every top-level binding (functions, consts, lets, destructured
+        // bindings). Used by the closure exemption: a function that references any
+        // of these closes over module scope, so extraction would sever that link.
+        const topLevelBindingNames = new Set();
+        // Whether the module references `require.main` — a CLI entry-point signal.
+        let referencesRequireMain = false;
         // Names that appear as the handler inside `export default someWrapper(name)`
         const wrappedDefaultHandlerNames = new Set();
         // Names directly exported as default (export default myFunc style via ExportDefaultDeclaration referencing an identifier)
@@ -272,6 +350,16 @@ exports.preferUtilityFunctionOwnFile = (0, createRule_1.createRule)({
         // Names exported via `export { foo, bar }` specifiers
         const specifierExportedNames = new Set();
         return {
+            // Detect `require.main` references (CLI entry-point signal)
+            MemberExpression(node) {
+                if (!node.computed &&
+                    node.object.type === utils_1.AST_NODE_TYPES.Identifier &&
+                    node.object.name === 'require' &&
+                    node.property.type === utils_1.AST_NODE_TYPES.Identifier &&
+                    node.property.name === 'main') {
+                    referencesRequireMain = true;
+                }
+            },
             // Collect export default declarations
             ExportDefaultDeclaration(node) {
                 hasExportDefault = true;
@@ -331,6 +419,7 @@ exports.preferUtilityFunctionOwnFile = (0, createRule_1.createRule)({
                 if (!node.id)
                     return;
                 const name = node.id.name;
+                topLevelBindingNames.add(name);
                 const isNamedExport = parent?.type === utils_1.AST_NODE_TYPES.ExportNamedDeclaration;
                 const isDefaultExport = parent?.type === utils_1.AST_NODE_TYPES.ExportDefaultDeclaration;
                 topLevelFunctions.push({
@@ -351,6 +440,9 @@ exports.preferUtilityFunctionOwnFile = (0, createRule_1.createRule)({
                     return;
                 const isNamedExport = parent?.type === utils_1.AST_NODE_TYPES.ExportNamedDeclaration;
                 for (const declarator of node.declarations) {
+                    // Every top-level binding (including non-function consts like a
+                    // registry array and destructured bindings) is a closure target.
+                    collectPatternNames(declarator.id, topLevelBindingNames);
                     if (declarator.id.type !== utils_1.AST_NODE_TYPES.Identifier)
                         continue;
                     const name = declarator.id.name;
@@ -366,7 +458,17 @@ exports.preferUtilityFunctionOwnFile = (0, createRule_1.createRule)({
                     });
                 }
             },
-            'Program:exit'() {
+            'Program:exit'(programNode) {
+                // CLI entry-point modules deliberately colocate their parser/printer/
+                // guard/compute helpers — those functions ARE the file's purpose, not
+                // foreign utilities. Recognize them via a `require.main` reference or a
+                // top-level self-invocation of one of their own functions
+                // (`void autoRunIfMain();`) and exempt the whole file.
+                const topLevelFunctionNames = new Set(topLevelFunctions.map((f) => f.name));
+                if (referencesRequireMain ||
+                    hasTopLevelSelfInvocation(programNode, topLevelFunctionNames)) {
+                    return;
+                }
                 // Determine the file's primary export name (basename heuristic)
                 // e.g. "modifyRoleMembers" in "modifyRoleMembers.f.ts"
                 const primaryName = basename;
@@ -419,7 +521,7 @@ exports.preferUtilityFunctionOwnFile = (0, createRule_1.createRule)({
                         continue;
                     // --- ignoreClosures: skip if the function body references module-scoped identifiers not passed as params ---
                     if (ignoreClosures) {
-                        const closesOverModuleScope = functionClosesOverModuleScope(fn, topLevelFunctions);
+                        const closesOverModuleScope = functionClosesOverModuleScope(fn, topLevelBindingNames);
                         if (closesOverModuleScope)
                             continue;
                     }
@@ -447,14 +549,14 @@ exports.preferUtilityFunctionOwnFile = (0, createRule_1.createRule)({
  * passed as parameters, making it non-trivially extractable.
  *
  * We identify "module-scope" identifiers as names of other top-level
- * declarations in the file (functions, variables) that are NOT imported.
- * Imported names and standard globals are considered "extractable" (you'd
- * just re-import them).
+ * declarations in the file (functions, variables, destructured bindings) that
+ * are NOT imported. Imported names and standard globals are considered
+ * "extractable" (you'd just re-import them).
  *
  * Strategy: collect referenced identifiers in the body, subtract param names,
  * then check if any remain that are names of other top-level declarations.
  */
-function functionClosesOverModuleScope(fn, topLevelFunctions) {
+function functionClosesOverModuleScope(fn, topLevelBindingNames) {
     const body = getFunctionBody(fn);
     if (!body)
         return false;
@@ -469,12 +571,10 @@ function functionClosesOverModuleScope(fn, topLevelFunctions) {
     for (const param of paramNames) {
         referencedIds.delete(param);
     }
-    // Get the set of top-level sibling function names
-    const topLevelNames = new Set(topLevelFunctions.map((f) => f.name));
-    // If ANY referenced identifier is a top-level sibling function name,
-    // then this function closes over a module-scope binding.
+    // If ANY referenced identifier is a top-level sibling binding name, then this
+    // function closes over module scope.
     for (const ref of referencedIds) {
-        if (topLevelNames.has(ref)) {
+        if (topLevelBindingNames.has(ref)) {
             return true;
         }
     }

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

@@ -232,18 +232,23 @@ function collectDependencies(fnNode, knownFunctionNames) {
     visit(fnNode.body);
     return [...dependencies];
 }
-function dependencyOrder(functions, direction) {
+function dependencyOrder(functions, direction, groupOrder) {
     const dependencyMap = new Map();
     const originalIndexMap = new Map(functions.map((fn) => [fn.name, fn.originalIndex]));
+    const groupRankMap = new Map(functions.map((fn) => [fn.name, groupOrder.indexOf(classifyGroup(fn))]));
     functions.forEach((fn) => {
         dependencyMap.set(fn.name, fn.dependencies);
     });
+    // Tiebreak among functions the call graph does NOT order relative to each
+    // other (independent roots, sibling callees, cycle members): configured
+    // group order first, then original source position. Both keys are intrinsic
+    // to the function rather than its current arrangement, so the traversal is a
+    // fixed point once reached — obeying a move never spawns a contradicting one.
+    const tiebreak = (a, b) => (groupRankMap.get(a) ?? 0) - (groupRankMap.get(b) ?? 0) ||
+        (originalIndexMap.get(a) ?? 0) - (originalIndexMap.get(b) ?? 0);
     const visited = new Set();
     const order = [];
-    const namesInOriginalOrder = functions
-        .slice()
-        .sort((a, b) => a.originalIndex - b.originalIndex)
-        .map((fn) => fn.name);
+    const namesInTiebreakOrder = functions.map((fn) => fn.name).sort(tiebreak);
     const incomingCount = new Map();
     functions.forEach((fn) => {
         if (!incomingCount.has(fn.name)) {
@@ -253,18 +258,13 @@ function dependencyOrder(functions, direction) {
             incomingCount.set(dep, (incomingCount.get(dep) || 0) + 1);
         });
     });
-    const roots = namesInOriginalOrder.filter((name) => (incomingCount.get(name) || 0) === 0);
+    const roots = namesInTiebreakOrder.filter((name) => (incomingCount.get(name) || 0) === 0);
     const visit = (name) => {
         if (visited.has(name)) {
             return;
         }
         visited.add(name);
-        const deps = dependencyMap
-            .get(name)
-            ?.slice()
-            .sort((a, b) => {
-            return ((originalIndexMap.get(a) || 0) - (originalIndexMap.get(b) || 0));
-        }) || [];
+        const deps = dependencyMap.get(name)?.slice().sort(tiebreak) || [];
         if (direction === 'callees-first') {
             deps.forEach(visit);
             order.push(name);
@@ -274,12 +274,15 @@ function dependencyOrder(functions, direction) {
             deps.forEach(visit);
         }
     };
-    [...roots, ...namesInOriginalOrder].forEach(visit);
+    // Depth-first from roots keeps each caller immediately above its own helper
+    // subtree (callers-first) — grouping call chains vertically. The call graph
+    // is primary; group order only breaks ties the graph leaves open.
+    [...roots, ...namesInTiebreakOrder].forEach(visit);
     return order;
 }
 function computeExpectedOrder(functions, options) {
     const groupOrder = normalizeGroupOrder(options.groupOrder);
-    const dependencySequence = dependencyOrder(functions, options.dependencyDirection);
+    const dependencySequence = dependencyOrder(functions, options.dependencyDirection, groupOrder);
     const dependencyRank = new Map(dependencySequence.map((name, idx) => [name, idx]));
     const exportRank = (fn) => {
         if (options.exportPlacement === 'ignore') {
@@ -290,10 +293,12 @@ function computeExpectedOrder(functions, options) {
         }
         return fn.isExported ? 1 : 0;
     };
-    const groupRank = (fn) => groupOrder.indexOf(classifyGroup(fn));
+    // Export placement is the only concern allowed to outrank the call graph.
+    // The dependency sequence already folds group order in as a tiebreak, so a
+    // caller is never sorted below the helpers it invokes on account of its verb
+    // prefix — the defect that produced self-contradicting move instructions.
     return functions.slice().sort((a, b) => {
         return (exportRank(a) - exportRank(b) ||
-            groupRank(a) - groupRank(b) ||
             (dependencyRank.get(a.name) ?? Number.MAX_SAFE_INTEGER) -
                 (dependencyRank.get(b.name) ?? Number.MAX_SAFE_INTEGER) ||
             a.originalIndex - b.originalIndex);
@@ -415,7 +420,11 @@ exports.verticallyGroupRelatedFunctions = (0, createRule_1.createRule)({
                         : 'exports stay at the bottom of the file';
                 const group = classifyGroup(misplacedInfo);
                 const groupOrder = normalizeGroupOrder(normalizedOptions.groupOrder);
-                const groupReason = groupOrder.indexOf(group) > 0
+                // Group order only settles ties the call graph leaves open, so cite it
+                // as a reason only when this function has no helpers of its own — never
+                // paired with "callers should sit above the helpers they invoke".
+                const groupReason = misplacedInfo.dependencies.length === 0 &&
+                    groupOrder.indexOf(group) > 0
                     ? `${group.replace('-', ' ')} should follow the configured group order`
                     : '';
                 const reasons = [dependencyReason, exportReason, groupReason]
@@ -459,7 +468,16 @@ exports.verticallyGroupRelatedFunctions = (0, createRule_1.createRule)({
                         const slice = node.body.slice(firstFunctionIndex, lastFunctionIndex + 1);
                         const blockContainsOnlyFunctions = slice.every((statement) => functionStatements.has(statement));
                         if (!blockContainsOnlyFunctions) {
-                            return null;
+                            // Real modules interleave type aliases, consts, and top-level
+                            // calls (e.g. `void autoRunIfMain();`) between functions. Rather
+                            // than bail, reorder only the function statements among their own
+                            // slots, leaving every other statement exactly where it is. Plain
+                            // node ranges keep the edits disjoint (no comment-span overlap
+                            // with the interleaved statements).
+                            return sourceOrderedInfos.map((info, idx) => {
+                                const target = expectedOrderInfos[idx];
+                                return fixer.replaceTextRange(info.statementNode.range, sourceCode.getText(target.statementNode));
+                            });
                         }
                         const [start] = statementRanges.get(node.body[firstFunctionIndex]) ||
                             getStatementRangeWithComments(node.body[firstFunctionIndex], sourceCode);

package/package.json

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

package/release-manifest.json

@@ -1,4 +1,40 @@
 [
+  {
+    "version": "1.18.12",
+    "date": "2026-07-12T03:45:44.071Z",
+    "rules": [
+      {
+        "name": "prefer-utility-function-own-file",
+        "changeType": "fix",
+        "issues": [
+          1285
+        ],
+        "summary": "exempt CLI entry-point and registry modules (closes #1285)"
+      },
+      {
+        "name": "vertically-group-related-functions",
+        "changeType": "fix",
+        "issues": [
+          1286
+        ],
+        "summary": "make call graph primary over name-prefix groups (closes #1286)"
+      }
+    ]
+  },
+  {
+    "version": "1.18.11",
+    "date": "2026-07-11T16:25:05.418Z",
+    "rules": [
+      {
+        "name": "parallelize-async-operations",
+        "changeType": "fix",
+        "issues": [
+          1284
+        ],
+        "summary": "treat throw-gated guard awaits as a sequencing barrier (closes #1284)"
+      }
+    ]
+  },
   {
     "version": "1.18.10",
     "date": "2026-07-11T15:24:03.394Z",