@blumintinc/eslint-plugin-blumint 1.20.145 → 1.20.147

package/lib/rules/prevent-children-clobber.js

@@ -103,33 +103,205 @@ function aliasDeclarationNamed(statement, name) {
         : undefined;
 }
 /**
- * Lexical alias lookup over pre-collected statement lists, innermost first, so
- * an inner declaration shadows a same-named outer one.
+ * The string members of `const NAME = ['a', 'b'] as const`, or `undefined` when
+ * the statement declares something else or an element is not a string literal.
+ *
+ * `prefer-union-from-const-array` rewrites a string-literal union alias into
+ * exactly this pair of declarations plus `(typeof NAME)[number]`, so a keep-list
+ * that reads decidable before that transform has to stay decidable after it.
+ */
+function constArrayMembersNamed(statement, name) {
+    const declared = (0, lexicalScope_1.declarationOf)(statement);
+    if (declared.type !== utils_1.AST_NODE_TYPES.VariableDeclaration ||
+        declared.kind !== 'const') {
+        return undefined;
+    }
+    for (const declarator of declared.declarations) {
+        if (declarator.id.type !== utils_1.AST_NODE_TYPES.Identifier ||
+            declarator.id.name !== name ||
+            declarator.init?.type !== utils_1.AST_NODE_TYPES.TSAsExpression) {
+            continue;
+        }
+        const { expression, typeAnnotation } = declarator.init;
+        // Without `as const` the elements widen to `string`, and the indexed access
+        // yields `string` rather than a union of the literals.
+        const isConstAssertion = typeAnnotation.type === utils_1.AST_NODE_TYPES.TSTypeReference &&
+            typeAnnotation.typeName.type === utils_1.AST_NODE_TYPES.Identifier &&
+            typeAnnotation.typeName.name === 'const';
+        if (!isConstAssertion || expression.type !== utils_1.AST_NODE_TYPES.ArrayExpression)
+            return undefined;
+        const members = [];
+        for (const element of expression.elements) {
+            if (element?.type !== utils_1.AST_NODE_TYPES.Literal ||
+                typeof element.value !== 'string') {
+                return undefined;
+            }
+            members.push(element.value);
+        }
+        return members;
+    }
+    return undefined;
+}
+/**
+ * Lexical lookup over pre-collected statement lists, innermost first, so an
+ * inner declaration shadows a same-named outer one.
  *
  * Resolution is by scope rather than by a map built during traversal because
  * type aliases hoist: a component declared above its own props alias must still
  * resolve it.
  */
 function aliasResolverFrom(lists, startIndex = 0) {
-    return (name) => {
-        for (let index = startIndex; index < lists.length; index += 1) {
-            for (const statement of lists[index]) {
-                const declaration = aliasDeclarationNamed(statement, name);
-                if (declaration) {
-                    return {
-                        typeNode: declaration.typeAnnotation,
-                        resolve: aliasResolverFrom(lists, index),
-                    };
+    return {
+        typeAlias(name) {
+            for (let index = startIndex; index < lists.length; index += 1) {
+                for (const statement of lists[index]) {
+                    const declaration = aliasDeclarationNamed(statement, name);
+                    if (declaration) {
+                        return {
+                            typeNode: declaration.typeAnnotation,
+                            resolve: aliasResolverFrom(lists, index),
+                        };
+                    }
                 }
             }
-        }
-        return undefined;
+            return undefined;
+        },
+        constArrayKeys(name) {
+            for (let index = startIndex; index < lists.length; index += 1) {
+                for (const statement of lists[index]) {
+                    const members = constArrayMembersNamed(statement, name);
+                    if (members)
+                        return members;
+                }
+            }
+            return undefined;
+        },
     };
 }
 function aliasResolverAt(from) {
     return aliasResolverFrom((0, lexicalScope_1.enclosingStatementLists)(from));
 }
-function typeNodeExcludesProperty(node, propertyName, resolveAlias, seen = new Set()) {
+/**
+ * The property names a `Pick<T, K>` keep-list names, or `null` when the list is
+ * not decidable from syntax alone.
+ *
+ * `null` means "prove nothing", never "keeps nothing": a keep-list spelled as a
+ * type parameter, `keyof T`, `string`, or a template-literal type can include
+ * `children`, and treating an undecidable list as an empty one would exempt
+ * exactly those.
+ */
+function stringLiteralKeySet(node, resolveAlias, seen = new Set()) {
+    if (node.type === utils_1.AST_NODE_TYPES.TSLiteralType) {
+        return node.literal.type === utils_1.AST_NODE_TYPES.Literal &&
+            typeof node.literal.value === 'string'
+            ? new Set([node.literal.value])
+            : null;
+    }
+    if (node.type === utils_1.AST_NODE_TYPES.TSUnionType) {
+        const keys = new Set();
+        for (const member of node.types) {
+            const memberKeys = stringLiteralKeySet(member, resolveAlias, seen);
+            if (!memberKeys)
+                return null;
+            for (const key of memberKeys) {
+                keys.add(key);
+            }
+        }
+        return keys;
+    }
+    // `(typeof KEYS)[number]` over a `const KEYS = [...] as const` names exactly
+    // the array's members — the spelling `prefer-union-from-const-array` rewrites
+    // a literal union alias into.
+    if (node.type === utils_1.AST_NODE_TYPES.TSIndexedAccessType &&
+        node.indexType.type === utils_1.AST_NODE_TYPES.TSNumberKeyword &&
+        node.objectType.type === utils_1.AST_NODE_TYPES.TSTypeQuery &&
+        node.objectType.exprName.type === utils_1.AST_NODE_TYPES.Identifier) {
+        const members = resolveAlias?.constArrayKeys(node.objectType.exprName.name);
+        return members ? new Set(members) : null;
+    }
+    // A bare alias standing for a literal union (`type Keys = 'sx' | 'size'`) is
+    // as decidable as the union written inline. A parameterized reference is not:
+    // it is a computed key list whose members this rule cannot enumerate.
+    if (node.type === utils_1.AST_NODE_TYPES.TSTypeReference &&
+        node.typeName.type === utils_1.AST_NODE_TYPES.Identifier &&
+        !node.typeParameters) {
+        const name = node.typeName.name;
+        if (!resolveAlias || seen.has(name))
+            return null;
+        const alias = resolveAlias.typeAlias(name);
+        if (!alias)
+            return null;
+        // Guarding before the recursion terminates a self-referential alias.
+        seen.add(name);
+        return stringLiteralKeySet(alias.typeNode, alias.resolve, seen);
+    }
+    return null;
+}
+/**
+ * Whether a closed object type provably declares no `propertyName` member.
+ *
+ * An index signature reopens the type — `{ [key: string]: unknown }` admits
+ * `children` — and so does a computed key the rule cannot evaluate, since the
+ * constant behind `[KEY]` may well be `'children'`. Both surrender the proof.
+ */
+function typeLiteralExcludesProperty(node, propertyName) {
+    return node.members.every((member) => {
+        if (member.type === utils_1.AST_NODE_TYPES.TSIndexSignature)
+            return false;
+        if (member.type !== utils_1.AST_NODE_TYPES.TSPropertySignature &&
+            member.type !== utils_1.AST_NODE_TYPES.TSMethodSignature) {
+            // Call and construct signatures declare no named member.
+            return true;
+        }
+        const key = member.key;
+        if (member.computed) {
+            return (key.type === utils_1.AST_NODE_TYPES.Literal &&
+                String(key.value) !== propertyName);
+        }
+        if (key.type === utils_1.AST_NODE_TYPES.Identifier) {
+            return key.name !== propertyName;
+        }
+        if (key.type === utils_1.AST_NODE_TYPES.Literal) {
+            return String(key.value) !== propertyName;
+        }
+        return false;
+    });
+}
+/**
+ * Generic wrappers that re-map a type's own members without contributing any of
+ * their own, so their argument still stands for the whole props type.
+ *
+ * `PropsWithChildren` is the counter-example the list exists for: it ADDS
+ * `children`, so a proof about its argument says nothing about the wrapper.
+ */
+const PROPERTY_PRESERVING_WRAPPERS = new Set([
+    'Readonly',
+    'Required',
+    'Partial',
+    'NonNullable',
+]);
+function wrapperNameOf(typeName) {
+    if (typeName.type === utils_1.AST_NODE_TYPES.Identifier)
+        return typeName.name;
+    if (typeName.type === utils_1.AST_NODE_TYPES.TSQualifiedName) {
+        return typeName.right.type === utils_1.AST_NODE_TYPES.Identifier
+            ? typeName.right.name
+            : null;
+    }
+    return null;
+}
+/**
+ * Whether a type node provably lacks `propertyName`.
+ *
+ * `closedLiteralCounts` records whether this position IS the props type rather
+ * than merely a part of it. Two of the proofs below — a `Pick<>` keep-list and
+ * a closed object literal — describe the type they sit on, so they only carry
+ * to the binding when nothing can add members on the way back out. The blanket
+ * recursion through a type reference's arguments is where that distinction
+ * bites: `PropsWithChildren<{ sx?: string }>` and `Record<string, { a: number }>`
+ * both wrap a children-free argument in something that admits `children`.
+ */
+function typeNodeExcludesProperty(node, propertyName, resolveAlias, seen = new Set(), closedLiteralCounts = false) {
     if (node.type === utils_1.AST_NODE_TYPES.TSTypeReference) {
         const typeName = node.typeName.type === utils_1.AST_NODE_TYPES.Identifier
             ? node.typeName.name
@@ -141,34 +313,62 @@ function typeNodeExcludesProperty(node, propertyName, resolveAlias, seen = new S
                 return true;
             }
         }
+        // A keep-list is a stronger guarantee than an omit-list: `Pick` drops every
+        // member it does not name, so a fully decidable list without `propertyName`
+        // excludes it outright.
+        if (closedLiteralCounts &&
+            typeName === 'Pick' &&
+            node.typeParameters?.params?.[1]) {
+            const kept = stringLiteralKeySet(node.typeParameters.params[1], resolveAlias);
+            if (kept && !kept.has(propertyName)) {
+                return true;
+            }
+        }
         if (node.typeParameters?.params) {
-            return node.typeParameters.params.some((param) => typeNodeExcludesProperty(param, propertyName, resolveAlias, seen));
+            const argumentsAreTheType = closedLiteralCounts &&
+                PROPERTY_PRESERVING_WRAPPERS.has(wrapperNameOf(node.typeName) ?? '');
+            return node.typeParameters.params.some((param) => typeNodeExcludesProperty(param, propertyName, resolveAlias, seen, argumentsAreTheType));
         }
-        if (typeName && resolveAlias && !seen.has(typeName)) {
-            const alias = resolveAlias(typeName);
+        // Keyed by position as well as by name: the same alias proves different
+        // things in a props position than inside an arbitrary generic, so a visit
+        // in one position must not suppress the visit in the other.
+        const seenKey = `${closedLiteralCounts ? 'props' : 'part'}:${typeName}`;
+        if (typeName && resolveAlias && !seen.has(seenKey)) {
+            const alias = resolveAlias.typeAlias(typeName);
             if (alias) {
                 // Guarding before the recursion terminates a self-referential alias.
-                seen.add(typeName);
-                if (typeNodeExcludesProperty(alias.typeNode, propertyName, alias.resolve, seen)) {
+                seen.add(seenKey);
+                if (typeNodeExcludesProperty(alias.typeNode, propertyName, alias.resolve, seen, closedLiteralCounts)) {
                     return true;
                 }
             }
         }
     }
+    if (node.type === utils_1.AST_NODE_TYPES.TSTypeLiteral) {
+        return (closedLiteralCounts && typeLiteralExcludesProperty(node, propertyName));
+    }
     if (node.type === utils_1.AST_NODE_TYPES.TSUnionType) {
-        return node.types.every((typeNode) => typeNodeExcludesProperty(typeNode, propertyName, resolveAlias, seen));
+        return node.types.every((typeNode) => typeNodeExcludesProperty(typeNode, propertyName, resolveAlias, seen, closedLiteralCounts));
     }
     if (node.type === utils_1.AST_NODE_TYPES.TSIntersectionType) {
-        return node.types.every((typeNode) => typeNodeExcludesProperty(typeNode, propertyName, resolveAlias, seen));
+        return node.types.every((typeNode) => typeNodeExcludesProperty(typeNode, propertyName, resolveAlias, seen, closedLiteralCounts));
     }
     return false;
 }
-function typeAnnotationExcludesProperty(annotation, propertyName, resolveAlias) {
-    if (!annotation)
+/**
+ * Entry point for a type node that stands for a whole props type, whether it
+ * was written as a parameter annotation or supplied as a `forwardRef` type
+ * argument.
+ */
+function propsTypeNodeExcludesProperty(typeNode, propertyName, resolveAlias) {
+    if (!typeNode)
         return false;
-    return typeNodeExcludesProperty(annotation.typeAnnotation, propertyName, resolveAlias);
+    return typeNodeExcludesProperty(typeNode, propertyName, resolveAlias, new Set(), true);
+}
+function typeAnnotationExcludesProperty(annotation, propertyName, resolveAlias) {
+    return propsTypeNodeExcludesProperty(annotation?.typeAnnotation, propertyName, resolveAlias);
 }
-function collectRestBindingsFromPattern(pattern, ctx, annotation, resolveAlias, sourceChildrenSourceId) {
+function collectRestBindingsFromPattern(pattern, ctx, typeNode, resolveAlias, sourceChildrenSourceId) {
     const childrenPresent = patternHasChildrenProperty(pattern);
     for (const prop of pattern.properties) {
         if (prop.type === utils_1.AST_NODE_TYPES.RestElement &&
@@ -177,7 +377,7 @@ function collectRestBindingsFromPattern(pattern, ctx, annotation, resolveAlias,
             ctx.bindings.set(prop.argument.name, {
                 identifier: prop.argument,
                 childrenExcluded: childrenPresent,
-                typeAnnotationExcludesProperty: typeAnnotationExcludesProperty(annotation, 'children', resolveAlias),
+                typeAnnotationExcludesProperty: propsTypeNodeExcludesProperty(typeNode, 'children', resolveAlias),
                 childrenSourceId: sourceChildrenSourceId ?? prop.argument.name,
             });
         }
@@ -212,13 +412,31 @@ function recordChildrenValueBindingsFromPattern(pattern, ctx, sourceChildrenSour
         }
     }
 }
-function recordParamBindings(param, ctx, resolveAlias) {
+/**
+ * The props type a parameter carries: its own annotation when it has one, and
+ * otherwise the type the call site supplies contextually.
+ *
+ * An explicit annotation always wins. It is the type the body is checked
+ * against, so a `forwardRef<E, Clean>((props: MenuProps, ref) => …)` still
+ * carries whatever `MenuProps` declares.
+ */
+function propsTypeNodeOf(param, contextualTypeNode) {
+    // A `TSParameterProperty` (a constructor's `private x: T`) carries its
+    // annotation on the parameter it wraps and never takes part in a component's
+    // props, so it simply has no props type of its own.
+    const own = param.type === utils_1.AST_NODE_TYPES.TSParameterProperty
+        ? undefined
+        : param.typeAnnotation?.typeAnnotation;
+    return own ?? contextualTypeNode;
+}
+function recordParamBindings(param, ctx, resolveAlias, contextualTypeNode) {
+    const typeNode = propsTypeNodeOf(param, contextualTypeNode);
     if (param.type === utils_1.AST_NODE_TYPES.Identifier) {
         ctx.propsLikeIdentifiers.add(param.name);
         ctx.bindings.set(param.name, {
             identifier: param,
             childrenExcluded: false,
-            typeAnnotationExcludesProperty: typeAnnotationExcludesProperty(param.typeAnnotation, 'children', resolveAlias),
+            typeAnnotationExcludesProperty: propsTypeNodeExcludesProperty(typeNode, 'children', resolveAlias),
             childrenSourceId: param.name,
         });
         return;
@@ -229,20 +447,61 @@ function recordParamBindings(param, ctx, resolveAlias) {
         ctx.bindings.set(param.left.name, {
             identifier: param.left,
             childrenExcluded: false,
-            typeAnnotationExcludesProperty: typeAnnotationExcludesProperty(param.typeAnnotation, 'children', resolveAlias),
+            typeAnnotationExcludesProperty: propsTypeNodeExcludesProperty(typeNode, 'children', resolveAlias),
             childrenSourceId: param.left.name,
         });
         return;
     }
     if (param.type === utils_1.AST_NODE_TYPES.AssignmentPattern &&
         param.left.type === utils_1.AST_NODE_TYPES.ObjectPattern) {
-        collectRestBindingsFromPattern(param.left, ctx, param.typeAnnotation, resolveAlias);
+        collectRestBindingsFromPattern(param.left, ctx, typeNode, resolveAlias);
         return;
     }
     if (param.type === utils_1.AST_NODE_TYPES.ObjectPattern) {
-        collectRestBindingsFromPattern(param, ctx, param.typeAnnotation, resolveAlias);
+        collectRestBindingsFromPattern(param, ctx, typeNode, resolveAlias);
     }
 }
+/**
+ * The props type a `forwardRef<Element, Props>(…)` call supplies to its render
+ * callback, whose parameters carry no annotation of their own.
+ *
+ * Without this the props type is invisible in the `forwardRef` spelling, so
+ * even the documented `Omit<…, 'children'>` remedy could not be seen and the
+ * rule reported on props it could prove children-free in every other spelling.
+ */
+function forwardRefPropsTypeNode(node) {
+    const call = node.parent;
+    if (call?.type !== utils_1.AST_NODE_TYPES.CallExpression)
+        return undefined;
+    if (call.arguments[0] !== node)
+        return undefined;
+    // An optional call detaches the type arguments onto a
+    // `TSInstantiationExpression` — `forwardRef<E, P>?.(…)` parses as
+    // instantiate-then-call — so both the callee and the type arguments are read
+    // through it. The node predates the `LeftHandSideExpression` union this
+    // version declares, hence the hand-written narrowing.
+    const rawCallee = call.callee;
+    const instantiation = rawCallee.type === utils_1.AST_NODE_TYPES.TSInstantiationExpression
+        ? rawCallee
+        : undefined;
+    const callee = instantiation?.expression ?? call.callee;
+    const calleeName = callee.type === utils_1.AST_NODE_TYPES.Identifier
+        ? callee.name
+        : callee.type === utils_1.AST_NODE_TYPES.MemberExpression &&
+            !callee.computed &&
+            callee.property.type === utils_1.AST_NODE_TYPES.Identifier
+            ? callee.property.name
+            : null;
+    if (calleeName !== 'forwardRef')
+        return undefined;
+    // `typeParameters` is where @typescript-eslint/utils 5 puts a call's type
+    // arguments; `typeArguments` is the name later majors use. Reading both keeps
+    // this working across the rename.
+    const instantiated = (instantiation ?? call);
+    const typeArguments = instantiated.typeParameters ?? instantiated.typeArguments;
+    // The first type argument is the element type; the props type is the second.
+    return typeArguments?.params?.[1];
+}
 function findNearestComponentContext(stack) {
     for (let i = stack.length - 1; i >= 0; i -= 1) {
         if (stack[i].isComponent)
@@ -460,9 +719,12 @@ exports.preventChildrenClobber = (0, createRule_1.createRule)({
                     // ESLint has assigned `parent` up the chain by the time this visitor
                     // runs, but not yet onto the parameter's own type annotation.
                     const resolveAlias = aliasResolverAt(node);
-                    for (const param of node.params) {
-                        recordParamBindings(param, ctx, resolveAlias);
-                    }
+                    // Only the first parameter receives the contextual props type; the
+                    // second is the forwarded ref.
+                    const contextualPropsType = forwardRefPropsTypeNode(node);
+                    node.params.forEach((param, index) => {
+                        recordParamBindings(param, ctx, resolveAlias, index === 0 ? contextualPropsType : undefined);
+                    });
                 }
                 functionStack.push(ctx);
             },
@@ -528,7 +790,7 @@ exports.preventChildrenClobber = (0, createRule_1.createRule)({
                     const initBinding = findBinding(init.name, functionStack);
                     const sourceChildrenSourceId = initBinding?.childrenSourceId ?? init.name;
                     recordChildrenValueBindingsFromPattern(id, componentCtx, sourceChildrenSourceId);
-                    collectRestBindingsFromPattern(id, componentCtx, id.typeAnnotation ?? null, aliasResolverAt(node), sourceChildrenSourceId);
+                    collectRestBindingsFromPattern(id, componentCtx, id.typeAnnotation?.typeAnnotation ?? null, aliasResolverAt(node), sourceChildrenSourceId);
                 }
             },
             JSXElement(node) {

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

@@ -422,6 +422,109 @@ function collectReferencedNames(node) {
     visit(node, null);
     return names;
 }
+// Type-space shells whose contents are erased at runtime. A reference inside
+// one (`const x: ReturnType<typeof buildHit> = …`) never reads the binding at
+// module evaluation, so it must not count as an eager reference — counting it
+// would withhold autofixes that are perfectly safe to apply.
+const TYPE_SPACE_NODE_TYPES = new Set([
+    'TSTypeAnnotation',
+    'TSTypeParameterInstantiation',
+    'TSTypeParameterDeclaration',
+    'TSTypeAliasDeclaration',
+    'TSInterfaceDeclaration',
+    'TSTypeQuery',
+    'TSDeclareFunction',
+]);
+// Names a statement reads at MODULE EVALUATION time. A read inside a function
+// body is deferred to call time and constrains nothing — except when that
+// function is an immediately invoked callee, which runs during evaluation. The
+// distinction is the whole point of this rule: callers referencing helpers
+// inside their bodies is the safe pattern being enforced, while an initializer
+// calling a helper runs the moment the module loads.
+function collectEagerlyReferencedNames(node) {
+    const names = new Set();
+    const visit = (current, parent) => {
+        if (!current || !ASTHelpers_1.ASTHelpers.isNode(current)) {
+            return;
+        }
+        if (TYPE_SPACE_NODE_TYPES.has(current.type)) {
+            return;
+        }
+        // An `as`/`satisfies` wrapper evaluates only its expression; the type side
+        // is erased.
+        if (current.type === 'TSAsExpression' ||
+            current.type === 'TSSatisfiesExpression') {
+            visit(current.expression, current);
+            return;
+        }
+        if (current.type === 'FunctionDeclaration' ||
+            current.type === 'FunctionExpression' ||
+            current.type === 'ArrowFunctionExpression') {
+            // Deferred to call time — unless this function is the callee of the call
+            // being visited, which the CallExpression case enters directly.
+            return;
+        }
+        if (current.type === 'CallExpression' &&
+            (current.callee.type === 'ArrowFunctionExpression' ||
+                current.callee.type === 'FunctionExpression')) {
+            // An IIFE's body runs during module evaluation, so its reads are eager.
+            visit(current.callee.body, current.callee);
+            current.callee.params.forEach((param) => visit(param, current.callee));
+            current.arguments.forEach((argument) => visit(argument, current));
+            return;
+        }
+        if (current.type === 'ClassDeclaration' ||
+            current.type === 'ClassExpression') {
+            // A class's heritage clause, computed member keys, static initializers,
+            // and static blocks all run at evaluation; method bodies and instance
+            // property values wait for construction.
+            visit(current.superClass, current);
+            current.body.body.forEach((member) => {
+                if (member.type === 'StaticBlock') {
+                    member.body.forEach((statement) => visit(statement, member));
+                    return;
+                }
+                if ('computed' in member && member.computed && 'key' in member) {
+                    visit(member.key, member);
+                }
+                if (member.type === 'PropertyDefinition' &&
+                    member.static &&
+                    member.value) {
+                    visit(member.value, member);
+                }
+            });
+            return;
+        }
+        if (current.type === 'Identifier') {
+            const isMemberProperty = parent?.type === 'MemberExpression' &&
+                parent.property === current &&
+                !parent.computed;
+            const isObjectKey = parent?.type === 'Property' &&
+                parent.key === current &&
+                !parent.computed;
+            if (!isMemberProperty && !isObjectKey) {
+                names.add(current.name);
+            }
+        }
+        Object.values(current).forEach((value) => {
+            if (!value || value === current || current.parent === value) {
+                return;
+            }
+            if (Array.isArray(value)) {
+                value.forEach((child) => {
+                    if (ASTHelpers_1.ASTHelpers.isNode(child)) {
+                        visit(child, current);
+                    }
+                });
+            }
+            else if (ASTHelpers_1.ASTHelpers.isNode(value)) {
+                visit(value, current);
+            }
+        });
+    };
+    visit(node, null);
+    return names;
+}
 // Names bound by an interleaved VALUE declaration (const/let/var) — but not by a
 // reorderable function. Hoisting a function above a value binding it references
 // is a genuine runtime declare-before-use. Type aliases are tracked separately
@@ -548,6 +651,50 @@ function reorderHoistsFunctionAboveDependency(regionStatements, functionStatemen
     }
     return false;
 }
+// Decline (return true) any reorder that would place a const/let/var-declared
+// function BELOW an interleaved statement that reads it at module evaluation
+// time. The fixer pins interleaved statements and swaps functions among their
+// own slots, so a helper `const` can be carried past its own module-scope
+// caller (`const CHAMPION = buildHit(…)`) — the emitted file parses and
+// type-checks but throws `ReferenceError: Cannot access '…' before
+// initialization` the moment anything imports it, and `--fix` reports nothing
+// about the file it just broke. Function declarations hoist, so demoting one
+// past an eager reference stays loadable and is not declined. This is the
+// mirror of reorderHoistsFunctionAboveDependency: that guard protects a moved
+// function from losing a dependency ABOVE it; this one protects a pinned
+// statement from losing its dependency BELOW it.
+function reorderDemotesDeclarationBelowEagerReference(regionStatements, functionStatements, expectedOrderInfos) {
+    const variableDeclaredNames = new Set();
+    expectedOrderInfos.forEach((info) => {
+        const declaration = info.statementNode.type === 'ExportNamedDeclaration'
+            ? info.statementNode.declaration
+            : info.statementNode;
+        if (declaration?.type === 'VariableDeclaration') {
+            variableDeclaredNames.add(info.name);
+        }
+    });
+    if (variableDeclaredNames.size === 0) {
+        return false;
+    }
+    const placedNames = new Set();
+    let slotCursor = 0;
+    for (const statement of regionStatements) {
+        if (functionStatements.has(statement)) {
+            const occupant = expectedOrderInfos[slotCursor];
+            slotCursor += 1;
+            if (occupant) {
+                placedNames.add(occupant.name);
+            }
+            continue;
+        }
+        for (const name of collectEagerlyReferencedNames(statement)) {
+            if (variableDeclaredNames.has(name) && !placedNames.has(name)) {
+                return true;
+            }
+        }
+    }
+    return false;
+}
 exports.verticallyGroupRelatedFunctions = (0, createRule_1.createRule)({
     name: 'vertically-group-related-functions',
     meta: {
@@ -729,6 +876,13 @@ exports.verticallyGroupRelatedFunctions = (0, createRule_1.createRule)({
                         if (reorderHoistsFunctionAboveDependency(slice, functionStatements, expectedOrderInfos)) {
                             return null;
                         }
+                        // The mirror hazard: a const-declared helper carried below a pinned
+                        // statement that calls it at module evaluation. The emitted file
+                        // would throw at import time, so the rewrite is withheld; the
+                        // misorderedFunction report still fires.
+                        if (reorderDemotesDeclarationBelowEagerReference(slice, functionStatements, expectedOrderInfos)) {
+                            return null;
+                        }
                         if (!blockContainsOnlyFunctions) {
                             // Real modules interleave type aliases, consts, and top-level
                             // calls (e.g. `void autoRunIfMain();`) between functions. Rather

package/package.json

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

package/release-manifest.json

@@ -1,4 +1,56 @@
 [
+  {
+    "version": "1.20.147",
+    "date": "2026-08-13T06:24:35.769Z",
+    "rules": [
+      {
+        "name": "no-entire-object-hook-deps",
+        "changeType": "fix",
+        "issues": [
+          1985
+        ],
+        "summary": "stop hoisting a guarded dereference into the dependency array (closes #1985)"
+      }
+    ]
+  },
+  {
+    "version": "1.20.146",
+    "date": "2026-08-13T00:14:52.842Z",
+    "rules": [
+      {
+        "name": "enforce-memoize-async",
+        "changeType": "fix",
+        "issues": [
+          1975
+        ],
+        "summary": "exempt methods taking part in a transaction (closes #1975)"
+      },
+      {
+        "name": "prefer-use-deep-compare-memo",
+        "changeType": "fix",
+        "issues": [
+          1979
+        ],
+        "summary": "stop promoting primitive deps via member access (closes #1979)"
+      },
+      {
+        "name": "prevent-children-clobber",
+        "changeType": "fix",
+        "issues": [
+          1980
+        ],
+        "summary": "widen the syntactic exemption beyond Omit<> (closes #1980)"
+      },
+      {
+        "name": "vertically-group-related-functions",
+        "changeType": "fix",
+        "issues": [
+          1983
+        ],
+        "summary": "decline reorders that demote a helper below its module-scope caller (closes #1983)"
+      }
+    ]
+  },
   {
     "version": "1.20.145",
     "date": "2026-08-12T16:05:12.174Z",