@blumintinc/eslint-plugin-blumint 1.20.145 → 1.20.146

package/lib/index.js

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

package/lib/rules/enforce-memoize-async.js

@@ -196,6 +196,246 @@ function declaresFunctionParameter(params) {
     }
     return parameterAnnotation(params[0])?.type === utils_1.AST_NODE_TYPES.TSFunctionType;
 }
+/**
+ * A database transaction handle is valid only for the attempt that created it,
+ * and a transaction body is re-run whenever the driver retries — Firestore
+ * retries an attempt whose reads a concurrent write invalidated. A memoized
+ * body hands the retry the first attempt's cached promise, so the retry queues
+ * no writes on its own handle, commits empty, and the caller reads the first
+ * attempt's return value and reports success. Memoizing the method that OWNS
+ * the transaction is the same defect one level up: the whole transaction, writes
+ * included, then runs once per instance.
+ */
+const TRANSACTION_TYPE_NAME = 'Transaction';
+const RUN_TRANSACTION_NAME = 'runTransaction';
+/**
+ * Keys that hold source positions or the tree's only back-edge rather than
+ * child nodes; `parent` would make a subtree walk non-terminating.
+ */
+const NON_TRAVERSABLE_KEYS = new Set(['parent', 'range', 'loc', 'type']);
+/** Every node of `root`'s subtree, `root` included. */
+function* subtreeOf(root) {
+    yield root;
+    for (const [key, value] of Object.entries(root)) {
+        if (NON_TRAVERSABLE_KEYS.has(key)) {
+            continue;
+        }
+        if (Array.isArray(value)) {
+            for (const element of value) {
+                if (ASTHelpers_1.ASTHelpers.isNode(element)) {
+                    yield* subtreeOf(element);
+                }
+            }
+        }
+        else if (ASTHelpers_1.ASTHelpers.isNode(value)) {
+            yield* subtreeOf(value);
+        }
+    }
+}
+/** The name a call invokes, for `f()` and for `o.f()` alike. */
+function calleeName(node) {
+    const callee = withoutChain(node.callee);
+    if (callee.type === utils_1.AST_NODE_TYPES.Identifier) {
+        return callee.name;
+    }
+    if (callee.type === utils_1.AST_NODE_TYPES.MemberExpression &&
+        !callee.computed &&
+        callee.property.type === utils_1.AST_NODE_TYPES.Identifier) {
+        return callee.property.name;
+    }
+    return undefined;
+}
+/**
+ * Whether the node is a `runTransaction(…)` call, under any receiver:
+ * `db.runTransaction`, `firestore.runTransaction` and a bare imported
+ * `runTransaction` all open a retryable transaction.
+ */
+function isRunTransactionCall(node) {
+    return (node.type === utils_1.AST_NODE_TYPES.CallExpression &&
+        calleeName(node) === RUN_TRANSACTION_NAME);
+}
+/** Whether the method opens a transaction anywhere in its own body. */
+function ownsTransaction(fn) {
+    for (const node of subtreeOf(fn)) {
+        if (isRunTransactionCall(node)) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Whether a type name denotes the transaction handle. The rightmost segment is
+ * the type's own name, so the qualified spellings — `FirebaseFirestore.
+ * Transaction`, `admin.firestore.Transaction` — answer alongside the bare one;
+ * a locally aliased import (`import { Transaction as Txn }`) answers through
+ * the alias set the file's imports define.
+ */
+function namesTransaction(typeName, aliases) {
+    if (typeName.type === utils_1.AST_NODE_TYPES.Identifier) {
+        return (typeName.name === TRANSACTION_TYPE_NAME || aliases.has(typeName.name));
+    }
+    if (typeName.type === utils_1.AST_NODE_TYPES.TSQualifiedName) {
+        return typeName.right.name === TRANSACTION_TYPE_NAME;
+    }
+    return false;
+}
+/**
+ * Whether a declared type hands the method a transaction handle: written
+ * directly, as one arm of a union or intersection, or as a property of an
+ * object type — the shape a destructured `{ transaction }: { transaction:
+ * Transaction }` parameter carries.
+ *
+ * Type ARGUMENTS are deliberately not entered: `Map<string, Transaction>` or
+ * `Promise<Transaction>` describes a collection of handles or a handle yet to
+ * exist, neither of which is the attempt-scoped handle this carve-out is about.
+ */
+function declaresTransactionType(annotation, aliases) {
+    if (!annotation) {
+        return false;
+    }
+    if (annotation.type === utils_1.AST_NODE_TYPES.TSTypeReference) {
+        return namesTransaction(annotation.typeName, aliases);
+    }
+    if (annotation.type === utils_1.AST_NODE_TYPES.TSUnionType ||
+        annotation.type === utils_1.AST_NODE_TYPES.TSIntersectionType) {
+        return annotation.types.some((member) => declaresTransactionType(member, aliases));
+    }
+    if (annotation.type === utils_1.AST_NODE_TYPES.TSTypeLiteral) {
+        return annotation.members.some((member) => member.type === utils_1.AST_NODE_TYPES.TSPropertySignature &&
+            declaresTransactionType(member.typeAnnotation?.typeAnnotation, aliases));
+    }
+    return false;
+}
+/**
+ * The type annotation a parameter declares, including the destructuring shapes
+ * `parameterAnnotation` does not reach: an object or array pattern carries its
+ * annotation on the pattern itself.
+ */
+function bindingAnnotation(param) {
+    if (param.type === utils_1.AST_NODE_TYPES.ObjectPattern ||
+        param.type === utils_1.AST_NODE_TYPES.ArrayPattern) {
+        return param.typeAnnotation?.typeAnnotation;
+    }
+    return parameterAnnotation(param);
+}
+/**
+ * Whether the method declares a parameter typed as a transaction handle.
+ *
+ * The test reads the ANNOTATION, not the parameter's name: a parameter merely
+ * named `transaction` is as likely to hold a payment or a ledger entry, and the
+ * rule's other carve-outs (void result, callback parameter) are annotation-driven
+ * for the same reason. A bare `async apply(transaction)` therefore keeps
+ * reporting — it declares nothing to honour, and under the `noImplicitAny` its
+ * consumers compile with it does not type-check anyway. Where the handle arrives
+ * through an unresolvable alias (`args: MembershipArgs`), the call-site test
+ * below is what recognises it.
+ */
+function declaresTransactionParameter(params, aliases) {
+    return params.some((param) => declaresTransactionType(bindingAnnotation(param), aliases));
+}
+/**
+ * The expression itself, with any `ChainExpression` wrapper removed. ESTree
+ * wraps a whole optional chain in that node, so `this?.body` and
+ * `this.body.bind?.(this)` reach a bare member/call test as something else
+ * entirely. Nullish spellings carry the transaction handle exactly as the plain
+ * ones do, and reading through the wrapper is what keeps the carve-out from
+ * lapsing on them — a lapse that would restore the empty-commit autofix.
+ */
+function withoutChain(node) {
+    return node.type === utils_1.AST_NODE_TYPES.ChainExpression
+        ? withoutChain(node.expression)
+        : node;
+}
+/** The own-method name a `this.foo` reference reads, if it reads one. */
+function thisMemberName(node) {
+    const expression = withoutChain(node);
+    if (expression.type === utils_1.AST_NODE_TYPES.MemberExpression &&
+        !expression.computed &&
+        withoutChain(expression.object).type === utils_1.AST_NODE_TYPES.ThisExpression &&
+        expression.property.type === utils_1.AST_NODE_TYPES.Identifier) {
+        return expression.property.name;
+    }
+    // `this.body.bind(this)` passes the same method, one wrapper out.
+    if (expression.type === utils_1.AST_NODE_TYPES.CallExpression &&
+        expression.callee.type === utils_1.AST_NODE_TYPES.MemberExpression &&
+        !expression.callee.computed &&
+        expression.callee.property.type === utils_1.AST_NODE_TYPES.Identifier &&
+        expression.callee.property.name === 'bind') {
+        return thisMemberName(expression.callee.object);
+    }
+    return undefined;
+}
+/** Whether the subtree mentions the binding, under any nesting. */
+function mentionsBinding(node, name) {
+    for (const descendant of subtreeOf(node)) {
+        if (descendant.type === utils_1.AST_NODE_TYPES.Identifier &&
+            descendant.name === name) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Own methods a `runTransaction` argument hands the attempt to: the method
+ * passed as the callback itself, and every `this.method(…)` the callback body
+ * invokes with the attempt's handle among its arguments.
+ *
+ * Passing the handle on is what makes a method part of the attempt, so a
+ * helper the callback calls WITHOUT it — a config read, a lookup that takes no
+ * transaction — is untouched and keeps reporting.
+ */
+function collectTransactionParticipants(argument, participants) {
+    const passed = thisMemberName(argument);
+    if (passed) {
+        participants.add(passed);
+        return;
+    }
+    if (argument.type !== utils_1.AST_NODE_TYPES.ArrowFunctionExpression &&
+        argument.type !== utils_1.AST_NODE_TYPES.FunctionExpression) {
+        return;
+    }
+    const handle = argument.params[0];
+    if (handle?.type !== utils_1.AST_NODE_TYPES.Identifier) {
+        return;
+    }
+    for (const node of subtreeOf(argument.body)) {
+        if (node.type !== utils_1.AST_NODE_TYPES.CallExpression) {
+            continue;
+        }
+        const method = thisMemberName(node.callee);
+        if (method &&
+            node.arguments.some((arg) => mentionsBinding(arg, handle.name))) {
+            participants.add(method);
+        }
+    }
+}
+/** Every own method the class hands a transaction handle to. */
+function transactionParticipantsOf(body) {
+    const participants = new Set();
+    for (const node of subtreeOf(body)) {
+        if (!isRunTransactionCall(node)) {
+            continue;
+        }
+        for (const argument of node.arguments) {
+            collectTransactionParticipants(argument, participants);
+        }
+    }
+    return participants;
+}
+/** The statically known name of a method, for matching call sites against it. */
+function methodName(node) {
+    if (node.computed) {
+        return undefined;
+    }
+    const { key } = node;
+    if (key.type === utils_1.AST_NODE_TYPES.Identifier) {
+        return key.name;
+    }
+    if (key.type === utils_1.AST_NODE_TYPES.Literal && typeof key.value === 'string') {
+        return key.value;
+    }
+    return undefined;
+}
 /**
  * Matches a memoize decorator in supported syntaxes:
  * - @Alias()
@@ -290,6 +530,66 @@ exports.enforceMemoizeAsync = (0, createRule_1.createRule)({
             }
             return memoizeImportCache;
         };
+        /**
+         * Local names bound to an imported `Transaction` type, so that an aliased
+         * import (`import { Transaction as Txn } from 'firebase-admin/firestore'`)
+         * is read as the handle it is. The module is not constrained: a handle is
+         * re-exported through as many paths as a codebase has layers, and the
+         * imported NAME already carries the signal.
+         */
+        let transactionAliasCache = null;
+        const transactionAliases = () => {
+            if (!transactionAliasCache) {
+                transactionAliasCache = new Set();
+                for (const statement of context.sourceCode.ast.body) {
+                    if (statement.type !== utils_1.AST_NODE_TYPES.ImportDeclaration) {
+                        continue;
+                    }
+                    for (const spec of statement.specifiers) {
+                        if (spec.type === utils_1.AST_NODE_TYPES.ImportSpecifier &&
+                            spec.imported.type === utils_1.AST_NODE_TYPES.Identifier &&
+                            spec.imported.name === TRANSACTION_TYPE_NAME) {
+                            transactionAliasCache.add(spec.local.name);
+                        }
+                    }
+                }
+            }
+            return transactionAliasCache;
+        };
+        /**
+         * The class-level scan is shared by every method of the class, so it runs
+         * once per class body rather than once per candidate method.
+         */
+        const participantCache = new WeakMap();
+        const transactionParticipants = (body) => {
+            let participants = participantCache.get(body);
+            if (!participants) {
+                participants = transactionParticipantsOf(body);
+                participantCache.set(body, participants);
+            }
+            return participants;
+        };
+        /**
+         * Whether the method takes part in a database transaction attempt, either
+         * by opening one or by being handed the attempt's handle. Caching such a
+         * method is never an optimisation: a retried attempt would replay the first
+         * attempt's promise, writing nothing on its own handle while the caller
+         * reads a success it did not get.
+         */
+        const participatesInTransaction = (node, fn) => {
+            if (declaresTransactionParameter(fn.params, transactionAliases())) {
+                return true;
+            }
+            if (ownsTransaction(fn)) {
+                return true;
+            }
+            const body = node.parent;
+            if (body?.type !== utils_1.AST_NODE_TYPES.ClassBody) {
+                return false;
+            }
+            const name = methodName(node);
+            return name !== undefined && transactionParticipants(body).has(name);
+        };
         return {
             MethodDefinition(node) {
                 // Only process async instance methods (skip static methods)
@@ -341,6 +641,17 @@ exports.enforceMemoizeAsync = (0, createRule_1.createRule)({
                 if (declaresVoidResult(node.value.returnType)) {
                     return;
                 }
+                // A transaction handle is valid only for the attempt that created it,
+                // so a result derived from one must not outlive that attempt. Caching
+                // the body of a `runTransaction` callback — or the method that owns the
+                // call — turns the retry a concurrent write provokes into a silent
+                // no-op: the retry replays the first attempt's promise, queues nothing
+                // on its own handle, commits empty, and reports the first attempt's
+                // value as success. The fixer would apply that unattended under
+                // `--fix`, so both report and fix are withheld.
+                if (participatesInTransaction(node, node.value)) {
+                    return;
+                }
                 const { aliases: memoizeAliases, namespaces: memoizeNamespaces } = memoizeImports();
                 const hasMemoizeImport = memoizeAliases.size > 0 || memoizeNamespaces.size > 0;
                 // Check if method already has @Memoize or @Memoize() decorator

package/lib/rules/prefer-use-deep-compare-memo.js

@@ -84,31 +84,315 @@ function isNonPrimitiveWithoutTypes(expr) {
             return false;
     }
 }
-// TypeScript-aware check. Defensive and conservative.
-function isNonPrimitiveWithTypes(context, expr) {
+/**
+ * Layer A: what the type checker proves about a dependency expression.
+ *
+ * Reading the type at the *reference* rather than at the declaration is
+ * deliberate: control-flow narrowing is what makes an optional `a?: string`
+ * answer `string` at the site React actually compares.
+ */
+function primitivenessByType(context, expr) {
     const services = context.parserServices;
     if (!services?.program || !services?.esTreeNodeToTSNodeMap) {
-        return false;
+        return 'unproven';
     }
     try {
+        // Dereferenced inside the function rather than at module scope: reading
+        // `ts.TypeFlags` while the module is being loaded takes the whole plugin
+        // down wherever `typescript` is not yet resolvable (#1354).
         // eslint-disable-next-line @typescript-eslint/no-var-requires
         const ts = require('typescript');
         const checker = services.program.getTypeChecker();
         const tsNode = services.esTreeNodeToTSNodeMap.get(expr);
         if (!tsNode)
-            return false;
-        const type = checker.getTypeAtLocation(tsNode);
-        // Explicitly ignore functions even though they are non-primitive
-        if (type.getCallSignatures().length > 0)
-            return false;
-        // Avoid guessing for unknown/any or non-function types
-        if (type.flags & (ts.TypeFlags.Any | ts.TypeFlags.Unknown))
-            return false;
-        return false;
+            return 'unproven';
+        const primitiveFlags = ts.TypeFlags.StringLike |
+            ts.TypeFlags.NumberLike |
+            ts.TypeFlags.BooleanLike |
+            ts.TypeFlags.BigIntLike |
+            ts.TypeFlags.ESSymbolLike |
+            ts.TypeFlags.Null |
+            ts.TypeFlags.Undefined |
+            ts.TypeFlags.Void;
+        // `any` and `unknown` carry no shape, and an unresolved type parameter is
+        // whatever its caller supplies, so none of the three is an answer.
+        const uninformativeFlags = ts.TypeFlags.Any | ts.TypeFlags.Unknown | ts.TypeFlags.TypeParameter;
+        const classify = (candidate) => {
+            if (candidate.flags & uninformativeFlags)
+                return 'unproven';
+            if (candidate.isUnion()) {
+                const verdicts = candidate.types.map(classify);
+                if (verdicts.includes('unproven'))
+                    return 'unproven';
+                return verdicts.every((verdict) => verdict === 'primitive')
+                    ? 'primitive'
+                    : 'nonPrimitive';
+            }
+            return candidate.flags & primitiveFlags ? 'primitive' : 'nonPrimitive';
+        };
+        return classify(checker.getTypeAtLocation(tsNode));
     }
     catch {
+        return 'unproven';
+    }
+}
+/**
+ * Type nodes naming a primitive outright. A `TSTypeReference` is absent by
+ * design: an alias resolves only through the checker, which is Layer A's job.
+ */
+const PRIMITIVE_TYPE_KEYWORDS = new Set([
+    utils_1.AST_NODE_TYPES.TSStringKeyword,
+    utils_1.AST_NODE_TYPES.TSNumberKeyword,
+    utils_1.AST_NODE_TYPES.TSBooleanKeyword,
+    utils_1.AST_NODE_TYPES.TSBigIntKeyword,
+    utils_1.AST_NODE_TYPES.TSSymbolKeyword,
+    utils_1.AST_NODE_TYPES.TSNullKeyword,
+    utils_1.AST_NODE_TYPES.TSUndefinedKeyword,
+    utils_1.AST_NODE_TYPES.TSVoidKeyword,
+]);
+function isPrimitiveLiteralNode(node) {
+    if (node.type === utils_1.AST_NODE_TYPES.TemplateLiteral)
+        return true;
+    if (node.type === utils_1.AST_NODE_TYPES.UnaryExpression) {
+        // `-1` and `+1` are literal types spelled across two nodes.
+        return ((node.operator === '-' || node.operator === '+') &&
+            isPrimitiveLiteralNode(node.argument));
+    }
+    if (node.type !== utils_1.AST_NODE_TYPES.Literal)
+        return false;
+    // A regular expression literal is an object, and its `value` is null in
+    // hosts that cannot construct it — the same shape a `null` literal has.
+    if ('regex' in node && node.regex)
+        return false;
+    const { value } = node;
+    return (value === null ||
+        typeof value === 'string' ||
+        typeof value === 'number' ||
+        typeof value === 'boolean' ||
+        typeof value === 'bigint');
+}
+function isPrimitiveTypeNode(node) {
+    if (PRIMITIVE_TYPE_KEYWORDS.has(node.type))
+        return true;
+    if (node.type === utils_1.AST_NODE_TYPES.TSLiteralType) {
+        return isPrimitiveLiteralNode(node.literal);
+    }
+    // A union is primitive only if nothing in it can carry identity, which is
+    // what makes `string | undefined` — the type an optional parameter has —
+    // answer the same as `string`.
+    if (node.type === utils_1.AST_NODE_TYPES.TSUnionType) {
+        return node.types.length > 0 && node.types.every(isPrimitiveTypeNode);
+    }
+    return false;
+}
+function isUseStateCallee(callee) {
+    if (callee.type === utils_1.AST_NODE_TYPES.Identifier) {
+        return callee.name === 'useState';
+    }
+    return (callee.type === utils_1.AST_NODE_TYPES.MemberExpression &&
+        !callee.computed &&
+        callee.property.type === utils_1.AST_NODE_TYPES.Identifier &&
+        callee.property.name === 'useState');
+}
+/**
+ * Whether a `const [x] = useState(<primitive>)` binding holds a primitive.
+ *
+ * Only element 0 qualifies: element 1 is the setter, a function. The setter is
+ * also the only other writer of element 0, and the initial value types what it
+ * accepts, so the state stays whatever kind the initializer made it.
+ */
+function isPrimitiveUseStateElement(declarator, bound) {
+    const { id, init } = declarator;
+    if (id.type !== utils_1.AST_NODE_TYPES.ArrayPattern)
         return false;
+    if (id.elements[0] !== bound)
+        return false;
+    if (!init || init.type !== utils_1.AST_NODE_TYPES.CallExpression)
+        return false;
+    if (!isUseStateCallee(init.callee))
+        return false;
+    // An explicit type argument overrides whatever the initial value would have
+    // inferred, so it answers instead of the initializer.
+    const typeArguments = init.typeParameters?.params;
+    if (typeArguments && typeArguments.length > 0) {
+        return typeArguments.every(isPrimitiveTypeNode);
     }
+    const [initial] = init.arguments;
+    return initial !== undefined && isPrimitiveLiteralNode(initial);
+}
+/**
+ * Layer B: primitiveness the parser alone can see.
+ *
+ * This layer exists because Layer A goes blind exactly where the shared rule
+ * testers run it — with no `project`, `useState` imported from react resolves
+ * to `any`, and so does every `lib` type. Syntax the file spells out does not
+ * degrade that way.
+ */
+function isProvablyPrimitiveBinding(definition) {
+    const bound = definition.name;
+    if (bound.type !== utils_1.AST_NODE_TYPES.Identifier)
+        return false;
+    // An annotation constrains every assignment to the binding, so it answers for
+    // a `let` and a reassigned parameter just as it does for a `const`.
+    const annotation = bound.typeAnnotation?.typeAnnotation;
+    if (annotation)
+        return isPrimitiveTypeNode(annotation);
+    const declarator = definition.node;
+    const declaration = definition.parent;
+    if (declarator.type !== utils_1.AST_NODE_TYPES.VariableDeclarator)
+        return false;
+    // Without an annotation the initializer is the only evidence, and it only
+    // describes the binding for as long as nothing rebinds it.
+    if (!declaration ||
+        declaration.type !== utils_1.AST_NODE_TYPES.VariableDeclaration ||
+        declaration.kind !== 'const') {
+        return false;
+    }
+    if (declarator.id === bound) {
+        return declarator.init !== null && isPrimitiveLiteralNode(declarator.init);
+    }
+    return isPrimitiveUseStateElement(declarator, bound);
+}
+/**
+ * Members that exist on primitives and on nothing else in ordinary code.
+ *
+ * `length`, `slice`, `includes`, `indexOf`, `concat`, `at`, `toString` and
+ * `valueOf` are deliberately absent: arrays and objects carry them too, so
+ * vetoing on one would stop the rule seeing the array dependencies it exists
+ * to catch.
+ */
+const PRIMITIVE_ONLY_MEMBERS = new Set([
+    'toUpperCase',
+    'toLowerCase',
+    'toFixed',
+    'toPrecision',
+    'trim',
+    'trimStart',
+    'trimEnd',
+    'padStart',
+    'padEnd',
+    'charAt',
+    'charCodeAt',
+    'codePointAt',
+    'normalize',
+    'localeCompare',
+    'startsWith',
+    'endsWith',
+    'repeat',
+    'toExponential',
+]);
+/**
+ * The children of a node an identifier can be *referenced* from.
+ *
+ * A non-computed member's property and a non-computed key spell a name rather
+ * than read a binding, so counting them as occurrences would let an unrelated
+ * `other.trim` decide what `trim` denotes.
+ */
+function referencedChildren(node) {
+    const children = [];
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const record = node;
+    for (const key of Object.keys(record)) {
+        if (key === 'parent')
+            continue;
+        if (key === 'property' &&
+            node.type === utils_1.AST_NODE_TYPES.MemberExpression &&
+            !node.computed) {
+            continue;
+        }
+        if (key === 'key' &&
+            (node.type === utils_1.AST_NODE_TYPES.Property ||
+                node.type === utils_1.AST_NODE_TYPES.MethodDefinition ||
+                node.type === utils_1.AST_NODE_TYPES.PropertyDefinition) &&
+            !node.computed) {
+            continue;
+        }
+        const child = record[key];
+        if (!child)
+            continue;
+        if (Array.isArray(child)) {
+            for (const element of child) {
+                if (element && typeof element === 'object' && 'type' in element) {
+                    children.push(element);
+                }
+            }
+        }
+        else if (typeof child === 'object' && 'type' in child) {
+            children.push(child);
+        }
+    }
+    return children;
+}
+/**
+ * Layer C: every read of the name inside the callback is a member that only a
+ * primitive has.
+ *
+ * The weakest of the three layers, and the only one that reaches a binding the
+ * file gives no annotation and no initializer for — `const { asPath } =
+ * useRouter()` is the shape the consumer's hooks are written in. It answers
+ * only when *every* occurrence agrees: a computed access, a spread, or the bare
+ * name passed along says nothing about the value's shape, and one such
+ * occurrence withdraws the guess.
+ */
+function readsOnlyPrimitiveMembers(callback, name) {
+    let accesses = 0;
+    let proven = true;
+    const visit = (node) => {
+        if (!proven)
+            return;
+        if (node.type === utils_1.AST_NODE_TYPES.MemberExpression &&
+            node.object.type === utils_1.AST_NODE_TYPES.Identifier &&
+            node.object.name === name) {
+            if (node.computed ||
+                node.property.type !== utils_1.AST_NODE_TYPES.Identifier ||
+                !PRIMITIVE_ONLY_MEMBERS.has(node.property.name)) {
+                proven = false;
+                return;
+            }
+            accesses += 1;
+            return;
+        }
+        if (node.type === utils_1.AST_NODE_TYPES.Identifier && node.name === name) {
+            proven = false;
+            return;
+        }
+        for (const child of referencedChildren(node)) {
+            visit(child);
+        }
+    };
+    visit(callback.body);
+    return proven && accesses > 0;
+}
+/**
+ * The one binding a name denotes at a call site, or null when the answer is not
+ * a single declaration. A name with several definitions — a redeclared `var`, a
+ * merged declaration — describes more than one thing, and no one of them speaks
+ * for the reference.
+ */
+function soleDefinitionOf(context, node, name) {
+    const variable = ASTHelpers_1.ASTHelpers.findVariableInScope(ASTHelpers_1.ASTHelpers.getScope(context, node), name);
+    if (!variable || variable.defs.length !== 1)
+        return null;
+    return variable.defs[0];
+}
+/**
+ * Whether a dependency is *provably* a primitive, across all three layers.
+ *
+ * The direction is asymmetric on purpose. A missed deep comparison costs a
+ * recomputation; a deep comparison wrapped around a `string` costs an injected
+ * dependency, a new import and a hook that cannot help, so nothing short of a
+ * proof promotes a dependency here (#1979).
+ */
+function isProvablyPrimitiveDependency(context, call, callback, dep) {
+    const verdict = primitivenessByType(context, dep);
+    if (verdict === 'primitive')
+        return true;
+    const definition = soleDefinitionOf(context, call, dep.name);
+    if (definition && isProvablyPrimitiveBinding(definition))
+        return true;
+    // Method names are evidence only where nothing better exists: a checker that
+    // resolved the type has already answered, and answered from more than a name.
+    return (verdict === 'unproven' && readsOnlyPrimitiveMembers(callback, dep.name));
 }
 function collectMemoizedIdentifiers(context) {
     const memoized = new Set();
@@ -401,12 +685,8 @@ exports.preferUseDeepCompareMemo = (0, createRule_1.createRule)({
                     if (el.type === utils_1.AST_NODE_TYPES.SpreadElement)
                         continue;
                     const expr = el;
-                    // TS-aware check first
-                    let isNonPrimitive = isNonPrimitiveWithTypes(context, expr);
-                    // Fallback heuristic without type info for literals/arrays/objects/functions
-                    if (!isNonPrimitive) {
-                        isNonPrimitive = isNonPrimitiveWithoutTypes(expr);
-                    }
+                    // Syntactic classification for literals/arrays/objects/functions
+                    let isNonPrimitive = isNonPrimitiveWithoutTypes(expr);
                     // Identifier-specific heuristic: consider non-primitive only if used as object or function in callback
                     if (!isNonPrimitive && expr.type === utils_1.AST_NODE_TYPES.Identifier) {
                         // Imported identifiers are treated as stable
@@ -414,7 +694,15 @@ exports.preferUseDeepCompareMemo = (0, createRule_1.createRule)({
                             isNonPrimitive = false;
                         }
                         else if (identifierUsedAsObjectOrArray(callback, expr.name) &&
-                            !isIdentifierMemoizedAbove(expr.name, memoizedIds)) {
+                            !isIdentifierMemoizedAbove(expr.name, memoizedIds) &&
+                            // Reading a member off a name proves the receiver has members,
+                            // which every primitive also has: `slug.toUpperCase()` and
+                            // `cfg.a` are the same shape. The promotion therefore stands only
+                            // while the receiver is not provably a primitive — a bare
+                            // Identifier reaches this branch through no other signal, so the
+                            // veto can withhold nothing the rule established some other way
+                            // (#1979).
+                            !isProvablyPrimitiveDependency(context, node, callback, expr)) {
                             isNonPrimitive = true;
                         }
                     }

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

package/release-manifest.json

@@ -1,4 +1,42 @@
 [
+  {
+    "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",