@blumintinc/eslint-plugin-blumint 1.18.11 → 1.18.13

package/lib/index.js

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

package/lib/rules/no-compositing-layer-props.js

@@ -104,6 +104,38 @@ exports.noCompositingLayerProps = (0, createRule_1.createRule)({
             }
             return false;
         }
+        // A property key names a `@keyframes` at-rule when it is a string literal
+        // (`'@keyframes spin'`) or a template literal whose leading text starts the
+        // at-rule (`` [`@keyframes ${name}`] `` for a dynamically-named animation).
+        function keyNamesKeyframes(key) {
+            if (key.type === utils_1.AST_NODE_TYPES.Literal &&
+                typeof key.value === 'string') {
+                return /^\s*@keyframes/i.test(key.value);
+            }
+            if (key.type === utils_1.AST_NODE_TYPES.TemplateLiteral &&
+                key.quasis.length > 0) {
+                const leading = key.quasis[0].value.cooked ?? key.quasis[0].value.raw;
+                return /^\s*@keyframes/i.test(leading);
+            }
+            return false;
+        }
+        // Compositing props declared inside a `@keyframes` block are exempt.
+        // Animating `transform`/`opacity` via `@keyframes` is the web-standard,
+        // GPU-accelerated animation pattern; this rule targets gratuitous *static*
+        // layer promotion, not a deliberate keyframe animation. Scoped to
+        // descendants of the `@keyframes` value object, so a static compositing prop
+        // sitting as a *sibling* of the `@keyframes` key is still flagged.
+        function isInKeyframes(node) {
+            let current = node.parent;
+            while (current) {
+                if (current.type === utils_1.AST_NODE_TYPES.Property &&
+                    keyNamesKeyframes(current.key)) {
+                    return true;
+                }
+                current = current.parent;
+            }
+            return false;
+        }
         function isStyleContext(node) {
             let current = node;
             while (current?.parent) {
@@ -145,6 +177,9 @@ exports.noCompositingLayerProps = (0, createRule_1.createRule)({
             // Skip if not in a style context
             if (!isStyleContext(node))
                 return;
+            // Skip compositing props inside a @keyframes animation definition
+            if (isInKeyframes(node))
+                return;
             let propertyName = '';
             let propertyValue = '';
             // Get property name

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

@@ -206,6 +206,50 @@ exports.parallelizeAsyncOperations = (0, createRule_1.createRule)({
             }
             return null;
         }
+        /**
+         * Extracts the bare receiver identifier of an awaited *named-method* call:
+         * the `object` of a `MemberExpression` callee when that object is a plain
+         * identifier and the accessed member is a named method -- either a
+         * non-computed property (`versionRef.set(...)`) or a computed string-literal
+         * key (`api['getData']()`). Both denote invoking a method on the shared
+         * receiver, so they are equivalent for ordering purposes.
+         *
+         * Returns null when the receiver is not a bare identifier -- a computed
+         * chain (`realtimeDb.ref(path).remove()`), a nested member
+         * (`api.users.getAll()`), a `this`/`super` receiver, or a non-member callee.
+         * Also returns null for a numeric or dynamic index (`operations[0]()`,
+         * `operations[i]()`): those select a distinct callable from a container
+         * rather than invoking a method on a stateful receiver, so they are
+         * genuinely independent and must not be collapsed onto a shared receiver.
+         * Handles optional-call ChainExpressions.
+         */
+        function getCalleeReceiverName(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.object.type !== utils_1.AST_NODE_TYPES.Identifier) {
+                return null;
+            }
+            const property = callee.property;
+            const isNamedMember = callee.computed
+                ? property.type === utils_1.AST_NODE_TYPES.Literal &&
+                    typeof property.value === 'string'
+                : property.type === utils_1.AST_NODE_TYPES.Identifier;
+            if (!isNamedMember) {
+                return null;
+            }
+            return callee.object.name;
+        }
         /**
          * Checks if there are dependencies between await expressions
          */
@@ -290,6 +334,31 @@ exports.parallelizeAsyncOperations = (0, createRule_1.createRule)({
                     }
                 }
             }
+            // 6. Shared-receiver ordering barrier. Two awaited calls whose callees are
+            // member expressions on the SAME receiver identifier (e.g. `ref.set(x)`
+            // then `ref.get()`) can carry a read-after-write / write-after-write
+            // dependency: the later call may observe or overwrite state the earlier
+            // one produced on that shared object. Promise.all runs its operands
+            // concurrently, so it would race that ordering and let the read see the
+            // stale value. Keep such a run sequential. Skipping a genuinely
+            // independent pair of reads on one receiver is only a missed
+            // parallelization (a safe no-op), which is preferable to silently
+            // reordering a real data dependency. The receiver must be a bare
+            // identifier; computed chains and nested members are left untouched.
+            const receiverNames = awaitNodes.map((node) => {
+                const awaitExpr = getAwaitExpression(node);
+                return awaitExpr ? getCalleeReceiverName(awaitExpr) : null;
+            });
+            for (let i = 1; i < receiverNames.length; i++) {
+                const receiver = receiverNames[i];
+                if (!receiver)
+                    continue;
+                for (let j = 0; j < i; j++) {
+                    if (receiverNames[j] === receiver) {
+                        return true;
+                    }
+                }
+            }
             return false;
         }
         /**

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/react-memoize-literals.js

@@ -62,6 +62,30 @@ const HOOKS_ALLOWING_NESTED_LITERALS = new Set([
  * MUI's `sx` and the standard `style` prop both fall into this category.
  */
 const STYLE_JSX_ATTRIBUTE_NAMES = new Set(['sx', 'style']);
+/**
+ * Array iteration higher-order methods that invoke their callback argument
+ * synchronously and then discard it. A function literal passed directly as such
+ * a callback is never observed by any hook dependency, prop, effect, or memoized
+ * child, so re-creating it each render costs nothing and memoizing it buys
+ * nothing — the same "identity is never observably compared" rationale that
+ * exempts throw-argument literals. Matched by (non-computed) method name only;
+ * the rule is not type-aware, mirroring how the hook-argument sets work.
+ */
+const ITERATION_METHODS = new Set([
+    'map',
+    'filter',
+    'forEach',
+    'reduce',
+    'reduceRight',
+    'some',
+    'every',
+    'find',
+    'findIndex',
+    'findLast',
+    'findLastIndex',
+    'flatMap',
+    'sort',
+]);
 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 ??
@@ -82,6 +106,31 @@ function isHookName(name) {
 function isComponentName(name) {
     return !!name && /^[A-Z]/.test(name);
 }
+/**
+ * True when `node` is a function literal passed directly as an argument to an
+ * Array iteration method call (`items.map((x) => ...)`,
+ * `list.filter(fn)`, `xs.reduce(fn, init)`, ...). Such a callback is invoked
+ * synchronously during render and then discarded, so its referential identity
+ * is never observed. Matched by (non-computed) method name only, since the rule
+ * is not type-aware.
+ */
+function isIterationMethodCallback(node) {
+    if (node.type !== utils_1.AST_NODE_TYPES.ArrowFunctionExpression &&
+        node.type !== utils_1.AST_NODE_TYPES.FunctionExpression) {
+        return false;
+    }
+    const parent = node.parent;
+    if (!parent ||
+        parent.type !== utils_1.AST_NODE_TYPES.CallExpression ||
+        !parent.arguments.includes(node)) {
+        return false;
+    }
+    const callee = parent.callee;
+    return (callee.type === utils_1.AST_NODE_TYPES.MemberExpression &&
+        !callee.computed &&
+        callee.property.type === utils_1.AST_NODE_TYPES.Identifier &&
+        ITERATION_METHODS.has(callee.property.name));
+}
 /**
  * Type guard for parenthesized expressions to unwrap safely.
  * @param node Node to evaluate.
@@ -773,6 +822,18 @@ exports.reactMemoizeLiterals = (0, createRule_1.createRule)({
             if (isTerminalUsage(node)) {
                 return;
             }
+            // A function literal passed directly as the callback to an Array
+            // iteration method (.map/.filter/.reduce/.forEach/...) is invoked
+            // synchronously during render and then discarded, so its identity is
+            // never observed by a hook dependency, prop, effect, or memoized child —
+            // memoizing it buys nothing. The rule's own advice is also unfollowable
+            // here: the callback closes over loop/render scope so it can't be hoisted
+            // to module level, and useCallback can't run inside a .map loop. Inline
+            // functions passed as JSX-attribute props *inside* the callback body are
+            // separate nodes and remain flagged.
+            if (isIterationMethodCallback(node)) {
+                return;
+            }
             // Inline literals that resolve to a style JSX attribute (sx, style),
             // whether directly or via conditional/logical/array wrappers, are
             // consumed by the library without reference equality checks, so

package/lib/rules/require-props-composition.js

@@ -236,6 +236,88 @@ function getPropsTypeNameFromParam(funcNode) {
     }
     return null;
 }
+/**
+ * Returns the first-parameter type annotation node of a component function, or
+ * null when the parameter is untyped or a rest element. Unlike
+ * getPropsTypeNameFromParam, this returns the raw TypeNode (e.g. the whole
+ * `Omit<ParentProps, 'children'>`) so it can be tested for composition.
+ */
+function getFirstParamTypeNode(funcNode) {
+    const firstParam = funcNode.params[0];
+    if (!firstParam)
+        return null;
+    if ((firstParam.type === utils_1.AST_NODE_TYPES.Identifier ||
+        firstParam.type === utils_1.AST_NODE_TYPES.ObjectPattern) &&
+        firstParam.typeAnnotation) {
+        return firstParam.typeAnnotation.typeAnnotation;
+    }
+    return null;
+}
+/**
+ * Resolve the function node for a component name in the program, following a
+ * single-identifier alias (`const Live = LiveUnmemoized`) and unwrapping a HOC
+ * call (`memo((props) => ...)`). Returns null when no function is found. The
+ * `seen` set guards against alias cycles.
+ */
+function findComponentFunction(program, name, seen = new Set()) {
+    if (seen.has(name))
+        return null;
+    seen.add(name);
+    for (const stmt of program.body) {
+        const decl = stmt.type === utils_1.AST_NODE_TYPES.ExportNamedDeclaration
+            ? stmt.declaration
+            : stmt;
+        if (!decl)
+            continue;
+        if (decl.type === utils_1.AST_NODE_TYPES.FunctionDeclaration &&
+            decl.id?.name === name) {
+            return decl;
+        }
+        if (decl.type === utils_1.AST_NODE_TYPES.VariableDeclaration) {
+            for (const declarator of decl.declarations) {
+                if (declarator.id.type !== utils_1.AST_NODE_TYPES.Identifier ||
+                    declarator.id.name !== name ||
+                    !declarator.init) {
+                    continue;
+                }
+                const init = declarator.init;
+                if (init.type === utils_1.AST_NODE_TYPES.ArrowFunctionExpression ||
+                    init.type === utils_1.AST_NODE_TYPES.FunctionExpression) {
+                    return init;
+                }
+                if (init.type === utils_1.AST_NODE_TYPES.CallExpression) {
+                    const arg0 = init.arguments[0];
+                    if (arg0 &&
+                        (arg0.type === utils_1.AST_NODE_TYPES.ArrowFunctionExpression ||
+                            arg0.type === utils_1.AST_NODE_TYPES.FunctionExpression)) {
+                        return arg0;
+                    }
+                }
+                if (init.type === utils_1.AST_NODE_TYPES.Identifier) {
+                    return findComponentFunction(program, init.name, seen);
+                }
+            }
+        }
+    }
+    return null;
+}
+/**
+ * Resolve the type node that defines a rendered dependency's props: its
+ * `{Dep}Props` alias if one exists, otherwise the dependency component's
+ * first-parameter type annotation. Used to detect inverse composition, where
+ * the child derives its props from the parent's props type.
+ */
+function getDependencyPropsSourceType(program, depName) {
+    const alias = findPropsTypeAliasByName(program, toPropsTypeName(depName));
+    if (alias) {
+        return alias.typeAnnotation;
+    }
+    const fn = findComponentFunction(program, depName);
+    if (fn) {
+        return getFirstParamTypeNode(fn);
+    }
+    return null;
+}
 exports.requirePropsComposition = (0, createRule_1.createRule)({
     name: 'require-props-composition',
     meta: {
@@ -384,7 +466,20 @@ exports.requirePropsComposition = (0, createRule_1.createRule)({
             const missingComposition = [];
             for (const dep of depComponents) {
                 const expectedPropsType = toPropsTypeName(dep);
-                const composes = typeNodeComposesWithProps(propsTypeNode, expectedPropsType);
+                let composes = typeNodeComposesWithProps(propsTypeNode, expectedPropsType);
+                // Inverse composition: the child derives its props FROM this parent's
+                // props type (e.g. `Omit<ParentProps, 'children'>`, often with no named
+                // ChildProps at all). The parent is then the single shared source of
+                // truth, so the DRY guarantee is already met; requiring the parent to
+                // *also* compose from ChildProps would invert the source of truth or
+                // create a circular dependency.
+                if (!composes && propsTypeName) {
+                    const depPropsSource = getDependencyPropsSourceType(prog, dep);
+                    if (depPropsSource &&
+                        typeNodeComposesWithProps(depPropsSource, propsTypeName)) {
+                        composes = true;
+                    }
+                }
                 if (composes) {
                     composedWith.add(dep);
                 }

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.11",
+  "version": "1.18.13",
   "description": "Custom eslint rules for use within BluMint",
   "author": {
     "name": "Brodie McGuire",

package/release-manifest.json

@@ -1,4 +1,64 @@
 [
+  {
+    "version": "1.18.13",
+    "date": "2026-07-13T01:43:11.918Z",
+    "rules": [
+      {
+        "name": "no-compositing-layer-props",
+        "changeType": "fix",
+        "issues": [
+          1288
+        ],
+        "summary": "exempt transform/opacity inside @keyframes (closes #1288)"
+      },
+      {
+        "name": "parallelize-async-operations",
+        "changeType": "fix",
+        "issues": [
+          1287
+        ],
+        "summary": "don't flag write-then-read on the same receiver (closes #1287)"
+      },
+      {
+        "name": "react-memoize-literals",
+        "changeType": "fix",
+        "issues": [
+          1290
+        ],
+        "summary": "exempt Array iteration callbacks (.map/.filter/...) (closes #1290)"
+      },
+      {
+        "name": "require-props-composition",
+        "changeType": "fix",
+        "issues": [
+          1289
+        ],
+        "summary": "recognize inverse composition (child derives from parent) (closes #1289)"
+      }
+    ]
+  },
+  {
+    "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",